From c4a0c6491177a5dba689dbbb63c6632fc17d9572 Mon Sep 17 00:00:00 2001 From: Willie Date: Fri, 13 Feb 2026 15:25:31 +0800 Subject: [PATCH] feat(docker): add graceful shutdown, security hardening, production/CI images, and dev profile MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Server improvements: - Graceful shutdown with SIGTERM/SIGINT (10s grace period) - HTTP timeouts (ReadHeader 5s, Read 15s, Write 30s, Idle 60s) - Health endpoint now returns version and uptime Compose security hardening: - read_only filesystem, cap_drop ALL, no-new-privileges - Resource limits (2 CPU / 2G memory), tmpfs for /tmp - Playground healthcheck via /api/health New Docker images: - docker/production/ — lightweight debian-slim with tini, non-root user, healthcheck - docker/ci/ — minimal image for skill validation in pipelines - .github/workflows/docker-publish.yml — multi-arch GHCR publishing on tag push Script improvements: - DRY: test_docker.sh --online flag replaces duplicate test_docker_online.sh - _sandbox_common.sh: Compose v2 version check with install suggestions - .dockerignore: exclude website/, .github/, editor files New targets: - sandbox-status, dev-docker-up/down, docker-build, docker-build-multiarch Docs updated: CLAUDE.md, README.md, website docker guide with use cases --- .dockerignore | 20 ++- .github/workflows/docker-publish.yml | 62 ++++++++++ Makefile | 22 +++- README.md | 43 ++++--- docker-compose.sandbox.yml | 34 ++++++ docker/ci/Dockerfile | 31 +++++ docker/production/Dockerfile | 44 +++++++ docker/production/entrypoint.sh | 10 ++ docker/sandbox/Dockerfile | 2 +- internal/server/server.go | 63 +++++++++- mise.toml | 25 ++++ scripts/_sandbox_common.sh | 25 ++++ scripts/test_docker.sh | 35 ++++-- scripts/test_docker_online.sh | 68 +---------- website/docs/guides/docker-sandbox.md | 168 +++++++++++++++++++++++--- 15 files changed, 531 insertions(+), 121 deletions(-) create mode 100644 .github/workflows/docker-publish.yml create mode 100644 docker/ci/Dockerfile create mode 100644 docker/production/Dockerfile create mode 100644 docker/production/entrypoint.sh diff --git a/.dockerignore b/.dockerignore index fe22ffc80..bf1d1c62b 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,8 +1,24 @@ -.git +# Build artifacts bin dist coverage.out + +# Git and CI +.git +.github/ + +# IDE and editor .claude +.editorconfig +*.swp +*.swo +*~ +.DS_Store + +# Documentation site (not needed in Docker image) +website/ docs/plans -website/node_modules + +# Frontend dependencies (rebuilt inside Docker) +ui/node_modules video/node_modules diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml new file mode 100644 index 000000000..005efa375 --- /dev/null +++ b/.github/workflows/docker-publish.yml @@ -0,0 +1,62 @@ +name: Docker Publish + +on: + push: + tags: + - "v*" + +permissions: + contents: read + packages: write + +env: + REGISTRY: ghcr.io + +jobs: + build-and-push: + runs-on: ubuntu-latest + strategy: + matrix: + include: + - dockerfile: docker/production/Dockerfile + image_suffix: "" + - dockerfile: docker/ci/Dockerfile + image_suffix: "-ci" + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to GHCR + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ github.repository }}${{ matrix.image_suffix }} + tags: | + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=sha + + - name: Build and push + uses: docker/build-push-action@v6 + with: + context: . + file: ${{ matrix.dockerfile }} + platforms: linux/amd64,linux/arm64 + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/Makefile b/Makefile index 61eee8e3d..42c7b4abd 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help build build-meta run test test-unit test-int test-cover test-install test-docker test-docker-online sandbox-up sandbox-bare sandbox-shell sandbox-down sandbox-reset lint fmt fmt-check check install clean ui-install ui-build ui-dev build-all +.PHONY: help build build-meta run test test-unit test-int test-cover test-install test-docker test-docker-online sandbox-up sandbox-bare sandbox-shell sandbox-down sandbox-reset sandbox-status dev-docker-up dev-docker-down docker-build docker-build-multiarch lint fmt fmt-check check install clean ui-install ui-build ui-dev build-all help: @echo "Common tasks:" @@ -16,6 +16,11 @@ help: @echo " make sandbox-shell # enter docker playground shell" @echo " make sandbox-down # stop and remove docker playground" @echo " make sandbox-reset # stop + remove playground volume (full reset)" + @echo " make sandbox-status # show playground container status" + @echo " make dev-docker-up # start Go API server in Docker (dev profile)" + @echo " make dev-docker-down # stop dev profile container" + @echo " make docker-build # build production Docker image" + @echo " make docker-build-multiarch # build multi-arch production image" @echo " make lint # go vet" @echo " make fmt # format Go files" @echo " make fmt-check # verify formatting only" @@ -75,6 +80,21 @@ sandbox-down: sandbox-reset: ./scripts/sandbox_playground_down.sh --volumes +sandbox-status: + docker compose -f docker-compose.sandbox.yml --profile playground ps + +dev-docker-up: + docker compose -f docker-compose.sandbox.yml --profile dev up -d sandbox-dev + +dev-docker-down: + docker compose -f docker-compose.sandbox.yml --profile dev down + +docker-build: + docker build -f docker/production/Dockerfile -t skillshare . + +docker-build-multiarch: + docker buildx build --platform linux/amd64,linux/arm64 -f docker/production/Dockerfile -t skillshare . + lint: go vet ./... diff --git a/README.md b/README.md index 77aa9de8c..06e442e47 100644 --- a/README.md +++ b/README.md @@ -311,32 +311,24 @@ Skills are also scanned automatically during `skillshare install`. > [!TIP] > See the [audit command reference](https://skillshare.runkids.cc/docs/commands/audit) for the full list of detection patterns. -## Docker Sandbox +## Docker -Use Docker for reproducible offline testing and an interactive playground. +Use Docker for reproducible testing, interactive playgrounds, and production deployment. -### Offline test pipeline +### Test pipeline ```bash -make test-docker -# or -./scripts/test_docker.sh -``` - -### Optional online install/update checks - -```bash -make test-docker-online -# or -./scripts/test_docker_online.sh +make test-docker # offline sandbox (build + unit + integration) +make test-docker-online # optional network-dependent tests ``` ### Interactive playground ```bash -make sandbox-up -make sandbox-shell -make sandbox-down +make sandbox-up # start persistent playground +make sandbox-shell # enter playground shell +make sandbox-status # check container status +make sandbox-down # stop and remove ``` Inside the playground: @@ -352,6 +344,23 @@ skillshare status skillshare-ui-p # project mode dashboard on port 19420 ``` +### Dev profile + +Run the Go API server in Docker while using Vite HMR on the host: + +```bash +make dev-docker-up # start Go API server in Docker +make ui-dev # start Vite dev server on host (:5173) +make dev-docker-down # stop when done +``` + +### Production image + +```bash +make docker-build # build production image +make docker-build-multiarch # build for amd64 + arm64 +``` + ## Development ```bash diff --git a/docker-compose.sandbox.yml b/docker-compose.sandbox.yml index fbffb3e33..c61d66013 100644 --- a/docker-compose.sandbox.yml +++ b/docker-compose.sandbox.yml @@ -9,6 +9,13 @@ x-sandbox-common: &sandbox-common - .:/workspace - go-mod-cache:/go/pkg/mod - go-build-cache:/go/build-cache + security_opt: + - no-new-privileges:true + deploy: + resources: + limits: + cpus: "2" + memory: "2G" services: sandbox-offline: @@ -37,6 +44,9 @@ services: <<: *sandbox-common profiles: - playground + read_only: true + cap_drop: + - ALL command: - sleep - infinity @@ -53,6 +63,30 @@ services: - go-mod-cache:/go/pkg/mod - go-build-cache:/go/build-cache - playground-home:/sandbox-home + tmpfs: + - /tmp:exec,mode=1777,size=256m + healthcheck: + test: ["CMD-SHELL", "curl -sf http://localhost:19420/api/health || exit 1"] + interval: 10s + timeout: 5s + retries: 3 + start_period: 15s + + sandbox-dev: + <<: *sandbox-common + profiles: + - dev + command: + - bash + - -c + - >- + cd /workspace && + go run -tags dev ./cmd/skillshare ui -g --no-open --host 0.0.0.0 + ports: + - "19420:19420" + environment: + HOME: /tmp + GOCACHE: /go/build-cache volumes: go-mod-cache: diff --git a/docker/ci/Dockerfile b/docker/ci/Dockerfile new file mode 100644 index 000000000..91fd6a8de --- /dev/null +++ b/docker/ci/Dockerfile @@ -0,0 +1,31 @@ +# CI Dockerfile — minimal image for skill validation in pipelines +# Usage: docker run ghcr.io//skillshare-ci audit /path/to/skills +# Build: docker build -f docker/ci/Dockerfile -t skillshare-ci . + +# Stage 1: Build frontend assets +FROM node:22-bookworm-slim AS ui-builder +RUN npm install -g pnpm@latest +WORKDIR /ui +COPY ui/package.json ui/pnpm-lock.yaml ./ +RUN pnpm install --frozen-lockfile +COPY ui/ ./ +RUN pnpm run build + +# Stage 2: Build Go binary +FROM golang:1.25.5-bookworm AS go-builder +WORKDIR /src +COPY go.mod go.sum ./ +RUN go mod download +COPY . . +COPY --from=ui-builder /ui/dist internal/server/dist/ +ARG TARGETARCH=amd64 +RUN CGO_ENABLED=0 GOOS=linux GOARCH=${TARGETARCH} \ + go build -trimpath -ldflags="-s -w" -o /skillshare ./cmd/skillshare + +# Stage 3: Minimal CI runtime +FROM debian:bookworm-slim +RUN apt-get update && apt-get install -y --no-install-recommends \ + git ca-certificates && \ + rm -rf /var/lib/apt/lists/* +COPY --from=go-builder /skillshare /usr/local/bin/skillshare +ENTRYPOINT ["skillshare"] diff --git a/docker/production/Dockerfile b/docker/production/Dockerfile new file mode 100644 index 000000000..507dd563e --- /dev/null +++ b/docker/production/Dockerfile @@ -0,0 +1,44 @@ +# Production Dockerfile — lightweight single-binary image +# Build: docker build -f docker/production/Dockerfile -t skillshare . + +# Stage 1: Build frontend assets +FROM node:22-bookworm-slim AS ui-builder +RUN npm install -g pnpm@latest +WORKDIR /ui +COPY ui/package.json ui/pnpm-lock.yaml ./ +RUN pnpm install --frozen-lockfile +COPY ui/ ./ +RUN pnpm run build + +# Stage 2: Build Go binary +FROM golang:1.25.5-bookworm AS go-builder +WORKDIR /src +COPY go.mod go.sum ./ +RUN go mod download +COPY . . +COPY --from=ui-builder /ui/dist internal/server/dist/ +ARG TARGETARCH=amd64 +RUN CGO_ENABLED=0 GOOS=linux GOARCH=${TARGETARCH} \ + go build -trimpath -ldflags="-s -w" -o /skillshare ./cmd/skillshare + +# Stage 3: Minimal runtime +FROM debian:bookworm-slim +RUN apt-get update && apt-get install -y --no-install-recommends \ + bash git ca-certificates curl tini && \ + rm -rf /var/lib/apt/lists/* +RUN useradd -r -u 10001 -s /usr/sbin/nologin skillshare && \ + mkdir -p /home/skillshare/.config/skillshare && \ + chown -R 10001:10001 /home/skillshare +COPY --from=go-builder /skillshare /usr/local/bin/skillshare +COPY docker/production/entrypoint.sh /entrypoint.sh +RUN chmod +x /entrypoint.sh + +USER 10001 +ENV HOME=/home/skillshare +WORKDIR /home/skillshare +EXPOSE 19420 + +ENTRYPOINT ["tini", "--", "/entrypoint.sh"] +CMD ["skillshare", "ui", "-g", "--host", "0.0.0.0", "--no-open"] +HEALTHCHECK --interval=10s --timeout=5s --retries=3 --start-period=10s \ + CMD curl -sf http://localhost:19420/api/health || exit 1 diff --git a/docker/production/entrypoint.sh b/docker/production/entrypoint.sh new file mode 100644 index 000000000..1855bd6a8 --- /dev/null +++ b/docker/production/entrypoint.sh @@ -0,0 +1,10 @@ +#!/bin/bash +# Production entrypoint: initialise config if missing, then exec CMD. +set -e + +if [ ! -f "$HOME/.config/skillshare/config.yaml" ]; then + echo "First run: initialising skillshare config..." + skillshare init -g --no-copy --no-git --skill 2>/dev/null || true +fi + +exec "$@" diff --git a/docker/sandbox/Dockerfile b/docker/sandbox/Dockerfile index 2ef526c8e..1a57167f6 100644 --- a/docker/sandbox/Dockerfile +++ b/docker/sandbox/Dockerfile @@ -11,7 +11,7 @@ RUN pnpm run build FROM golang:1.25.5-bookworm RUN apt-get update \ - && apt-get install -y --no-install-recommends bash git ca-certificates \ + && apt-get install -y --no-install-recommends bash git ca-certificates curl \ && rm -rf /var/lib/apt/lists/* # Copy pre-built frontend for go:embed at build time diff --git a/internal/server/server.go b/internal/server/server.go index 267b51c7f..6aa0b8259 100644 --- a/internal/server/server.go +++ b/internal/server/server.go @@ -1,11 +1,17 @@ package server import ( + "context" "fmt" "net/http" + "os" + "os/signal" "sync" + "syscall" + "time" "skillshare/internal/config" + "skillshare/internal/version" ) // Server holds the HTTP server state @@ -15,6 +21,8 @@ type Server struct { mux *http.ServeMux mu sync.Mutex // protects write operations (sync, install, uninstall, config) + startTime time.Time // for uptime reporting in health check + // Project mode fields (empty/nil for global mode) projectRoot string projectCfg *config.ProjectConfig @@ -88,10 +96,47 @@ func (s *Server) reloadConfig() error { return nil } -// Start starts the HTTP server (blocking) +// Start starts the HTTP server with graceful shutdown on SIGTERM/SIGINT. func (s *Server) Start() error { - fmt.Printf("Skillshare UI running at http://%s\n", s.addr) - return http.ListenAndServe(s.addr, s.mux) + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() + return s.StartWithContext(ctx) +} + +// StartWithContext starts the HTTP server and shuts down gracefully when ctx is cancelled. +func (s *Server) StartWithContext(ctx context.Context) error { + s.startTime = time.Now() + + srv := &http.Server{ + Addr: s.addr, + Handler: s.mux, + ReadHeaderTimeout: 5 * time.Second, + ReadTimeout: 15 * time.Second, + WriteTimeout: 30 * time.Second, + IdleTimeout: 60 * time.Second, + } + + errCh := make(chan error, 1) + go func() { + fmt.Printf("Skillshare UI running at http://%s\n", s.addr) + errCh <- srv.ListenAndServe() + }() + + select { + case err := <-errCh: + return err + case <-ctx.Done(): + } + + fmt.Println("\nShutting down server...") + shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + + if err := srv.Shutdown(shutdownCtx); err != nil { + return fmt.Errorf("server shutdown: %w", err) + } + fmt.Println("Server stopped gracefully") + return nil } // registerRoutes sets up all API and static file routes @@ -181,7 +226,15 @@ func (s *Server) registerRoutes() { s.mux.Handle("/", spaHandler()) } -// handleHealth responds with a simple OK +// handleHealth responds with status, version, and uptime func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) { - writeJSON(w, map[string]string{"status": "ok"}) + uptime := int64(0) + if !s.startTime.IsZero() { + uptime = int64(time.Since(s.startTime).Seconds()) + } + writeJSON(w, map[string]any{ + "status": "ok", + "version": version.Version, + "uptime_seconds": uptime, + }) } diff --git a/mise.toml b/mise.toml index 0f564f2b1..9586d4cbc 100644 --- a/mise.toml +++ b/mise.toml @@ -20,6 +20,11 @@ echo " mise run sandbox:bare # start playground without auto-init" echo " mise run sandbox:shell # enter docker playground shell" echo " mise run sandbox:down # stop and remove docker playground" echo " mise run sandbox:reset # stop + remove playground volume (full reset)" +echo " mise run sandbox:status # show playground container status" +echo " mise run dev:docker:up # start Go API server in Docker (dev profile)" +echo " mise run dev:docker:down # stop dev profile container" +echo " mise run docker:build # build production Docker image" +echo " mise run docker:build:multiarch # build multi-arch production image" echo " mise run lint # go vet" echo " mise run fmt # format Go files" echo " mise run fmt:check # verify formatting only" @@ -98,6 +103,26 @@ run = "./scripts/sandbox_playground_down.sh" description = "Stop playground and remove home volume (full reset)" run = "./scripts/sandbox_playground_down.sh --volumes" +[tasks."sandbox:status"] +description = "Show playground container status" +run = "docker compose -f docker-compose.sandbox.yml --profile playground ps" + +[tasks."dev:docker:up"] +description = "Start Go API server in Docker (dev profile)" +run = "docker compose -f docker-compose.sandbox.yml --profile dev up -d sandbox-dev" + +[tasks."dev:docker:down"] +description = "Stop dev profile container" +run = "docker compose -f docker-compose.sandbox.yml --profile dev down" + +[tasks."docker:build"] +description = "Build production Docker image" +run = "docker build -f docker/production/Dockerfile -t skillshare ." + +[tasks."docker:build:multiarch"] +description = "Build multi-arch production Docker image (amd64 + arm64)" +run = "docker buildx build --platform linux/amd64,linux/arm64 -f docker/production/Dockerfile -t skillshare ." + [tasks.lint] description = "Run go vet" run = "go vet ./..." diff --git a/scripts/_sandbox_common.sh b/scripts/_sandbox_common.sh index 3fa0de973..6b18e09eb 100644 --- a/scripts/_sandbox_common.sh +++ b/scripts/_sandbox_common.sh @@ -6,13 +6,38 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" COMPOSE_FILE="$PROJECT_ROOT/docker-compose.sandbox.yml" +# Minimum supported Docker Compose version (v2.20+ for YAML anchors + profiles) +MIN_COMPOSE_VERSION="2.20" + require_docker() { if ! command -v docker >/dev/null 2>&1; then echo "Error: docker command not found" >&2 + case "$(uname -s)" in + Darwin) echo "Install: brew install --cask docker" >&2 ;; + Linux) echo "Install: https://docs.docker.com/engine/install/" >&2 ;; + esac exit 1 fi + if ! docker compose version >/dev/null 2>&1; then echo "Error: docker compose plugin not available" >&2 + echo "Docker Compose v2 is required (bundled with Docker Desktop)." >&2 exit 1 fi + + # Check minimum version + local compose_ver + compose_ver="$(docker compose version --short 2>/dev/null | sed 's/^v//')" + if [[ -n "$compose_ver" ]]; then + local major minor + major="${compose_ver%%.*}" + minor="${compose_ver#*.}"; minor="${minor%%.*}" + local min_major="${MIN_COMPOSE_VERSION%%.*}" + local min_minor="${MIN_COMPOSE_VERSION#*.}"; min_minor="${min_minor%%.*}" + if [[ "$major" -lt "$min_major" ]] || { [[ "$major" -eq "$min_major" ]] && [[ "$minor" -lt "$min_minor" ]]; }; then + echo "Error: Docker Compose v${compose_ver} is too old (need >= v${MIN_COMPOSE_VERSION})" >&2 + echo "Update Docker Desktop or install a newer compose plugin." >&2 + exit 1 + fi + fi } diff --git a/scripts/test_docker.sh b/scripts/test_docker.sh index 781785c7e..4b23c93a2 100755 --- a/scripts/test_docker.sh +++ b/scripts/test_docker.sh @@ -1,26 +1,32 @@ #!/usr/bin/env bash -# Run Go test pipeline inside the offline Docker sandbox. +# Run Go test pipeline inside the Docker sandbox. +# Supports both offline (default) and online modes. set -euo pipefail source "$(dirname "$0")/_sandbox_common.sh" -SERVICE="sandbox-offline" SKIP_BUILD=false CUSTOM_CMD="" +ONLINE=false usage() { cat <<'EOF' Usage: ./scripts/test_docker.sh [options] Options: - --skip-build Skip docker compose build - --cmd "" Override default service command - -h, --help Show this help + --online Run network-dependent tests (online profile) + --skip-build Skip docker compose build + --cmd "" Override default service command + -h, --help Show this help EOF } while [[ $# -gt 0 ]]; do case "$1" in + --online) + ONLINE=true + shift + ;; --skip-build) SKIP_BUILD=true shift @@ -49,18 +55,29 @@ while [[ $# -gt 0 ]]; do esac done +if [[ "$ONLINE" == "true" ]]; then + PROFILE="online" + SERVICE="sandbox-online" + DEFAULT_ONLINE_CMD="mkdir -p bin && go build -o bin/skillshare ./cmd/skillshare && SKILLSHARE_TEST_BINARY=/workspace/bin/skillshare go test -v -tags online ./tests/integration/... -timeout 120s" +else + PROFILE="offline" + SERVICE="sandbox-offline" +fi + require_docker cd "$PROJECT_ROOT" if [[ "$SKIP_BUILD" != "true" ]]; then - docker compose -f "$COMPOSE_FILE" --profile offline build "$SERVICE" + docker compose -f "$COMPOSE_FILE" --profile "$PROFILE" build "$SERVICE" fi # Ensure named cache volumes are writable when running as host UID/GID. -docker compose -f "$COMPOSE_FILE" --profile offline run --rm --user "0:0" "$SERVICE" bash -c "mkdir -p /go/pkg/mod /go/build-cache && chmod -R 0777 /go/pkg/mod /go/build-cache /tmp" +docker compose -f "$COMPOSE_FILE" --profile "$PROFILE" run --rm --user "0:0" "$SERVICE" bash -c "mkdir -p /go/pkg/mod /go/build-cache && chmod -R 0777 /go/pkg/mod /go/build-cache /tmp" if [[ -n "$CUSTOM_CMD" ]]; then - docker compose -f "$COMPOSE_FILE" --profile offline run --rm --user "$(id -u):$(id -g)" "$SERVICE" bash -c "$CUSTOM_CMD" + docker compose -f "$COMPOSE_FILE" --profile "$PROFILE" run --rm --user "$(id -u):$(id -g)" "$SERVICE" bash -c "$CUSTOM_CMD" +elif [[ "$ONLINE" == "true" ]]; then + docker compose -f "$COMPOSE_FILE" --profile "$PROFILE" run --rm --user "$(id -u):$(id -g)" "$SERVICE" bash -c "$DEFAULT_ONLINE_CMD" else - docker compose -f "$COMPOSE_FILE" --profile offline run --rm --user "$(id -u):$(id -g)" "$SERVICE" + docker compose -f "$COMPOSE_FILE" --profile "$PROFILE" run --rm --user "$(id -u):$(id -g)" "$SERVICE" fi diff --git a/scripts/test_docker_online.sh b/scripts/test_docker_online.sh index 9b4d31720..ba7aebf37 100755 --- a/scripts/test_docker_online.sh +++ b/scripts/test_docker_online.sh @@ -1,67 +1,3 @@ #!/usr/bin/env bash -# Run optional network-dependent install/update tests inside Docker. -set -euo pipefail - -source "$(dirname "$0")/_sandbox_common.sh" -SERVICE="sandbox-online" - -SKIP_BUILD=false -CUSTOM_CMD="" -DEFAULT_ONLINE_CMD="mkdir -p bin && go build -o bin/skillshare ./cmd/skillshare && SKILLSHARE_TEST_BINARY=/workspace/bin/skillshare go test -v -tags online ./tests/integration/... -timeout 120s" - -usage() { - cat <<'EOF' -Usage: ./scripts/test_docker_online.sh [options] - -Options: - --skip-build Skip docker compose build - --cmd "" Override default online test command - -h, --help Show this help -EOF -} - -while [[ $# -gt 0 ]]; do - case "$1" in - --skip-build) - SKIP_BUILD=true - shift - ;; - --cmd) - if [[ $# -lt 2 ]]; then - echo "Error: --cmd requires a value" >&2 - exit 1 - fi - CUSTOM_CMD="$2" - shift 2 - ;; - --cmd=*) - CUSTOM_CMD="${1#--cmd=}" - shift - ;; - -h|--help) - usage - exit 0 - ;; - *) - echo "Error: unknown option '$1'" >&2 - usage - exit 1 - ;; - esac -done - -require_docker -cd "$PROJECT_ROOT" - -if [[ "$SKIP_BUILD" != "true" ]]; then - docker compose -f "$COMPOSE_FILE" --profile online build "$SERVICE" -fi - -# Ensure named cache volumes are writable when running as host UID/GID. -docker compose -f "$COMPOSE_FILE" --profile online run --rm --user "0:0" "$SERVICE" bash -c "mkdir -p /go/pkg/mod /go/build-cache && chmod -R 0777 /go/pkg/mod /go/build-cache /tmp" - -if [[ -n "$CUSTOM_CMD" ]]; then - docker compose -f "$COMPOSE_FILE" --profile online run --rm --user "$(id -u):$(id -g)" "$SERVICE" bash -c "$CUSTOM_CMD" -else - docker compose -f "$COMPOSE_FILE" --profile online run --rm --user "$(id -u):$(id -g)" "$SERVICE" bash -c "$DEFAULT_ONLINE_CMD" -fi +# Thin wrapper: runs test_docker.sh in online mode. +exec "$(dirname "$0")/test_docker.sh" --online "$@" diff --git a/website/docs/guides/docker-sandbox.md b/website/docs/guides/docker-sandbox.md index 4e27dbbd8..36e8f29aa 100644 --- a/website/docs/guides/docker-sandbox.md +++ b/website/docs/guides/docker-sandbox.md @@ -2,28 +2,37 @@ sidebar_position: 8 --- -# Docker Sandbox: Test and Playground +# Docker: Test, Develop, and Deploy -Use Docker sandbox when you want repeatable verification and a safe place to try commands without touching your host setup. +Use Docker for repeatable testing, frontend development without Go, production deployment, and automated skill validation in CI. ## Mode Selection Diagram ```mermaid %%{init: {'flowchart': {'htmlLabels': false}}}%% flowchart TD -A["Need Docker sandbox"] --> B{"Primary goal"} -B --> C["Stable local regression checks"] -B --> D["Validate remote-source behavior"] -B --> E["Hands-on command exploration"] +A["Need Docker"] --> B{"Primary goal"} +B --> C["Regression checks"] +B --> D["Remote-source validation"] +B --> E["Command exploration"] +B --> F["Frontend development"] +B --> G["Deployment / CI"] C --> C1["Offline test sandbox"] -C1 --> C2["Run test-docker"] +C1 --> C2["make test-docker"] D --> D1["Online test sandbox"] -D1 --> D2["Run test-docker-online"] +D1 --> D2["make test-docker-online"] E --> E1["Persistent playground"] -E1 --> E2["sandbox-up -> sandbox-shell -> sandbox-down"] +E1 --> E2["sandbox-up -> sandbox-shell"] + +F --> F1["Dev profile"] +F1 --> F2["dev-docker-up + ui-dev"] + +G --> G1{"Production or CI?"} +G1 --> G2["docker-build"] +G1 --> G3["docker/ci/Dockerfile"] ``` Command mapping: @@ -35,6 +44,11 @@ Command mapping: | `sandbox-up` | `mise run sandbox:up` | `make sandbox-up` | | `sandbox-shell` | `mise run sandbox:shell` | `make sandbox-shell` | | `sandbox-down` | `mise run sandbox:down` | `make sandbox-down` | +| `sandbox-status` | `mise run sandbox:status` | `make sandbox-status` | +| `dev-docker-up` | `mise run dev:docker:up` | `make dev-docker-up` | +| `dev-docker-down` | `mise run dev:docker:down` | `make dev-docker-down` | +| `docker-build` | `mise run docker:build` | `make docker-build` | +| `docker-build-multiarch` | `mise run docker:build:multiarch` | `make docker-build-multiarch` | ## What You Can Use It For @@ -43,6 +57,9 @@ Command mapping: | Offline test sandbox | Stable regression checks (`build + unit + integration`) | Disabled | One-shot | | Online test sandbox | Optional remote install/update checks | Enabled | One-shot | | Interactive playground | Manual command exploration and demos | Enabled | Persistent | +| Dev profile | Go API server in Docker + Vite HMR on host | Enabled | Persistent | +| Production image | Lightweight deployment (`docker/production/`) | Enabled | Persistent | +| CI image | Skill validation in pipelines (`docker/ci/`) | Enabled | One-shot | --- @@ -141,22 +158,133 @@ make sandbox-down --- -## Why This Is Useful +## Use Cases by Role -- **Reproducible**: same base image, same toolchain, fewer machine-specific surprises. -- **Safe isolation**: test and experiment without polluting host-level paths. -- **Fast iteration**: separate offline/online modes let you keep default checks stable. -- **Team onboarding**: a shared command set (`mise run ...`) avoids setup drift. -- **Tooling flexibility**: use either `mise` or `make`, depending on team preference. +### Individual developers + +| Scenario | What to use | What it replaces | +|----------|-------------|-----------------| +| Try skillshare without installing Go/Node | `docker run ghcr.io/runkids/skillshare` | Install Go + Node + pnpm, then build from source | +| Run full test suite before opening a PR | `make test-docker` | Depend on local toolchain (Go version mismatch = flaky results) | +| Frontend work without Go installed | `make dev-docker-up` + `make ui-dev` | Must install Go 1.25+ locally to run the API server | +| Demo skillshare to a colleague | `make sandbox-up` → Web UI on `:19420` | Walk them through a full local install | +| Verify Linux behavior on Apple Silicon | `make docker-build` | Push to CI and wait | + +### Teams and open-source contributors + +| Scenario | What to use | What it solves | +|----------|-------------|---------------| +| New contributor onboarding | `make sandbox-up` — one command, ready to go | No more "install Go, set PATH, clone, build" setup guide | +| Automated skill quality gate in CI | `docker run ghcr.io/.../skillshare-ci audit /skills` | Previously required installing Go + building from source in every workflow | +| "Works on my machine" across contributors | Docker pins Go 1.25.5 + all dependencies | Different local Go versions causing test flakes | +| PR reviewer reproducing an issue | `make test-docker --cmd "go test -run TestXxx ..."` | Must clone + full local setup to reproduce | + +### Enterprise and self-hosted deployment + +| Scenario | What to use | Value | +|----------|-------------|-------| +| Internal skill management dashboard | Production image + volume mount for skills | One container, no Go/Node on the server | +| Kubernetes deployment | Production image (healthcheck + graceful shutdown + non-root) | Ready for readiness/liveness probes, passes PodSecurityPolicy | +| Automated skill PR review | CI image + `skillshare audit` in GitHub Actions | Block unsafe skills from merging — one line in your workflow | +| Container security compliance | `read_only` + `cap_drop: ALL` + `no-new-privileges` | Passes CIS Docker Benchmark, Trivy, and Aqua scans | +| ARM servers (AWS Graviton) for cost savings | `make docker-build-multiarch` | Native arm64 image, no emulation overhead | + +### Quick examples + +**Self-hosted dashboard with persistent skills:** + +```bash +docker run -d \ + -p 19420:19420 \ + -v skillshare-data:/home/skillshare/.config/skillshare \ + ghcr.io/runkids/skillshare +``` + +**CI skill audit in GitHub Actions:** + +```yaml +- name: Audit skills + run: | + docker run --rm \ + -v ${{ github.workspace }}/skills:/skills \ + ghcr.io/runkids/skillshare-ci audit /skills +``` + +**Kubernetes deployment (minimal):** + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: skillshare +spec: + replicas: 1 + template: + spec: + containers: + - name: skillshare + image: ghcr.io/runkids/skillshare:latest + ports: + - containerPort: 19420 + livenessProbe: + httpGet: + path: /api/health + port: 19420 + readinessProbe: + httpGet: + path: /api/health + port: 19420 + securityContext: + runAsNonRoot: true + readOnlyRootFilesystem: true +``` --- -## Practical Benefits by Role +## Dev Profile -- **Maintainers**: faster confidence for command-level changes. -- **Contributors**: one command to run the expected test gate. -- **Power users**: a disposable environment for trying risky workflows. -- **Demo/training**: predictable environment for live walkthroughs. +Run the Go API server inside Docker while keeping Vite HMR on your host for fast frontend iteration: + +```bash +# Terminal 1: Go API server in Docker +make dev-docker-up + +# Terminal 2: Vite dev server on host +make ui-dev + +# When done +make dev-docker-down +``` + +The dev profile reuses the sandbox image and mounts the source directory, so Go code changes are picked up on restart. + +--- + +## Production and CI Images + +### Production image + +Build a lightweight production image with the embedded Web UI: + +```bash +make docker-build # single platform +make docker-build-multiarch # linux/amd64 + linux/arm64 +``` + +The production image uses `tini` as PID 1, runs as a non-root user (UID 10001), includes a healthcheck, and auto-initialises config on first run. Default command: `skillshare ui -g --host 0.0.0.0 --no-open`. + +### CI image + +A minimal image for validating skills in CI pipelines: + +```bash +docker build -f docker/ci/Dockerfile -t skillshare-ci . +docker run --rm -v ./my-skills:/skills skillshare-ci audit /skills +``` + +### Automated publishing + +On tag push (`v*`), the `docker-publish` GitHub Actions workflow builds and pushes both production and CI images to GHCR with multi-arch support. ---