mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
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:
+18
-2
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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 ./...
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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"]
|
||||
@@ -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
|
||||
@@ -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 "$@"
|
||||
@@ -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
|
||||
|
||||
@@ -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,
|
||||
})
|
||||
}
|
||||
|
||||
@@ -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 ./..."
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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 "$@"
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user