feat(docker): add graceful shutdown, security hardening, production/CI images, and dev profile

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
This commit is contained in:
Willie
2026-02-13 15:29:52 +08:00
parent e5da171976
commit c4a0c64911
15 changed files with 531 additions and 121 deletions
+18 -2
View File
@@ -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
+62
View File
@@ -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
+21 -1
View File
@@ -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 ./...
+26 -17
View File
@@ -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
+34
View File
@@ -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:
+31
View File
@@ -0,0 +1,31 @@
# CI Dockerfile — minimal image for skill validation in pipelines
# Usage: docker run ghcr.io/<org>/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"]
+44
View File
@@ -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
+10
View File
@@ -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 "$@"
+1 -1
View File
@@ -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
+58 -5
View File
@@ -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,
})
}
+25
View File
@@ -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 ./..."
+25
View File
@@ -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
}
+26 -9
View File
@@ -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 "<command>" Override default service command
-h, --help Show this help
--online Run network-dependent tests (online profile)
--skip-build Skip docker compose build
--cmd "<command>" 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
+2 -66
View File
@@ -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 "<command>" 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 "$@"
+148 -20
View File
@@ -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.
---