From c4cdd083efeac96877b099a8d152df135ab52f7d Mon Sep 17 00:00:00 2001 From: Donovan Yohan Date: Wed, 8 Apr 2026 02:23:00 -0400 Subject: [PATCH 1/2] docs: improve setup guide with first-time build fixes and Tailscale section README: add build images section with local arm64 build instructions, clarify make build vs make all, add workstation server + Tailscale guide. Makefile: clarify that build target excludes web assets. build-images.yml: default to "all" target since "common" fails on first build. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/workflows/build-images.yml | 10 ++--- Makefile | 4 +- README.md | 59 ++++++++++++++++++++++++++++++ 3 files changed, 66 insertions(+), 7 deletions(-) diff --git a/.github/workflows/build-images.yml b/.github/workflows/build-images.yml index 801540647..c990da40c 100644 --- a/.github/workflows/build-images.yml +++ b/.github/workflows/build-images.yml @@ -21,14 +21,14 @@ on: description: 'Container registry (e.g., ghcr.io/myorg)' required: true target: - description: 'Build target' + description: 'Build target (use "all" for first-time builds)' type: choice options: - - common - all + - common - core-base - harnesses - default: 'common' + default: 'all' tag: description: 'Image tag' default: 'latest' @@ -48,9 +48,9 @@ on: required: true type: string target: - description: 'Build target (common, all, core-base, harnesses)' + description: 'Build target (all, common, core-base, harnesses)' type: string - default: 'common' + default: 'all' tag: description: 'Image tag' type: string diff --git a/Makefile b/Makefile index 14e763ed3..6eb5b4e5c 100644 --- a/Makefile +++ b/Makefile @@ -16,10 +16,10 @@ GOLANGCI_LINT := $(shell command -v golangci-lint 2>/dev/null || echo $(shell go .PHONY: all build install test test-fast vet lint golangci-lint web web-typecheck fmt fmt-check ci ci-full clean help container-sciontool container-scion container-binaries -## all: Build the web frontend, then compile the Go binary with embedded assets +## all: Build the web frontend + Go binary with embedded assets (required for the web UI) all: web install -## build: Compile the scion binary into ./build/ +## build: Compile the scion binary into ./build/ (without web assets — web UI will 404) build: @echo "Building $(BINARY)..." @mkdir -p $(BUILD_DIR) diff --git a/README.md b/README.md index 451f50731..3e04c5841 100644 --- a/README.md +++ b/README.md @@ -32,12 +32,46 @@ See the full [Installation Guide](https://googlecloudplatform.github.io/scion/ge go install github.com/GoogleCloudPlatform/scion/cmd/scion@latest ``` +If you've cloned the repo and want the **web UI** included, use `make all` (not `make build`): + +```bash +make all # builds web frontend + Go binary with embedded assets +``` + +> **Note:** `make build` compiles only the Go binary without web assets. The web UI will return 404s if you use `make build` alone. Use `make all` for a fully functional server with the browser-based frontend. + +### Build Container Images + +Fork the repo and use the **Build Scion Images** GitHub Actions workflow, or build locally. + +**GitHub Actions:** Go to Actions > "Build Scion Images" > Run workflow. Fill in: +- **Container registry**: `ghcr.io/` (e.g., `ghcr.io/myuser`) +- **Build target**: `all` (required for first-time builds — `common` assumes `core-base` already exists in your registry) +- **Image tag**: `latest` +- **Target platform(s)**: Match your machine architecture (see note below) + +> **Important — Apple Silicon users:** GitHub Actions runners are x86_64. Building `linux/arm64` images on these runners uses QEMU emulation and can take **over an hour**. For much faster builds, build locally instead: +> +> ```bash +> # Log in to GHCR +> gh auth token | docker login ghcr.io -u --password-stdin +> +> # Build and push (minutes on native arm64 vs. 1hr+ on GitHub Actions) +> image-build/scripts/build-images.sh \ +> --registry ghcr.io/ \ +> --target all \ +> --tag latest \ +> --platform linux/arm64 \ +> --push +> ``` + ### Initialize your machine and a Grove (project) Navigate to your project and create a Scion grove (the `.scion` directory that holds agent config) - use the registry where you built images: ```bash scion init --machine +scion config set --global image_registry ghcr.io/ cd my-project scion init ``` @@ -90,6 +124,31 @@ scion start debug "Help me debug this error" --attach Not all concepts apply in every scenario — local mode is simpler. See [Concepts](https://googlecloudplatform.github.io/scion/concepts/) for the full picture. +## Workstation Server with Tailscale + +The [workstation server](https://googlecloudplatform.github.io/scion/advanced-local/workstation-server/) runs Hub, Runtime Broker, and the web frontend as a single daemon. Combined with [Tailscale](https://tailscale.com/), you can orchestrate agents from any device on your tailnet. + +```bash +# Start the server (binds to localhost by default) +scion server start + +# Expose via Tailscale (HTTPS + your tailnet hostname, no config changes needed) +tailscale serve 8080 +``` + +Access the web UI at `https://:8080/` from any device on your tailnet. + +This approach keeps scion bound to loopback with its defaults — Tailscale handles network exposure and TLS termination. No need to use `--host 0.0.0.0`. + +Other useful server commands: + +| Command | Description | +|---------|-------------| +| `scion server status` | Check component health and daemon PID | +| `scion server stop` | Stop the daemon | +| `scion server restart` | Restart (picks up new binary after `make all`) | +| `scion server install` | Generate a launchd (macOS) or systemd (Linux) service file | + ## Documentation Visit our **[Documentation Site](https://googlecloudplatform.github.io/scion/)** for comprehensive guides and reference. From fd51f73a7d8b7f9ed532e03928457cdc8ddcb626 Mon Sep 17 00:00:00 2001 From: Preston Holmes Date: Thu, 9 Apr 2026 00:24:22 +0000 Subject: [PATCH 2/2] =?UTF-8?q?fix:=20correct=20Tailscale=20URL=20?= =?UTF-8?q?=E2=80=94=20serve=208080=20proxies=20to=20port=20443,=20not=20:?= =?UTF-8?q?8080?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3e04c5841..4b8043f81 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ scion server start tailscale serve 8080 ``` -Access the web UI at `https://:8080/` from any device on your tailnet. +Access the web UI at `https:///` from any device on your tailnet. This approach keeps scion bound to loopback with its defaults — Tailscale handles network exposure and TLS termination. No need to use `--host 0.0.0.0`.