feat(devcontainer): standalone lifecycle without VS Code dependency

`make devc` now builds, initialises, and enters the devcontainer in one
step — no VS Code required. A unified `scripts/devc.sh` replaces the old
`devcontainer_shell.sh` with full lifecycle subcommands (up/shell/down/
restart/reset/status).

Key changes:
- Dockerfile Stage 2 copies node+pnpm from ui-builder (removes need for
  devcontainer feature, benefits sandbox playground too)
- profile.d scripts moved from setup.sh → start-dev.sh so they survive
  container recreation (down → up) without re-running full setup
- Volume-based sentinel (~/.devcontainer-initialized) lets devc.sh skip
  setup.sh when volumes persist, cutting restart to ~2s
- Go toolchain PATH added to profile.d (login shell was losing it)
- Makefile/mise.toml gain devc-up/-down/-restart/-reset/-status targets
- Website docs updated with terminal-first flow and CLI path in diagrams
This commit is contained in:
Willie
2026-03-03 16:08:11 +08:00
parent bcbbaaf34d
commit 474bf3e4c1
10 changed files with 284 additions and 81 deletions
-6
View File
@@ -3,12 +3,6 @@
"dockerComposeFile": "docker-compose.yml",
"service": "skillshare-devcontainer",
"workspaceFolder": "/workspace",
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "24",
"pnpmVersion": "10.28.0"
}
},
"forwardPorts": [5173, 19420, 3000],
"portsAttributes": {
"5173": { "label": "Dashboard (ui)" },
+7 -23
View File
@@ -12,29 +12,10 @@ if [[ "${HOME:-}" != "/tmp" && "${HOME:-}" != "/home/developer" ]] || [ ! -d /wo
fi
cd /workspace
# ── 0. Token env: .env overrides host-passed env vars ────────────────
# Docker-compose passes host tokens via environment (fallback).
# If .devcontainer/.env exists, source it in every login shell to override.
cat > /etc/profile.d/skillshare-env.sh << 'PROFILE_EOF'
if [ -f /workspace/.devcontainer/.env ]; then
set -a
. /workspace/.devcontainer/.env
set +a
fi
PROFILE_EOF
# Keep devcontainer command wrappers ahead of /usr/local/bin in login shells.
cat > /etc/profile.d/skillshare-path.sh << 'PROFILE_EOF'
case ":$PATH:" in
*:/workspace/.devcontainer/bin:*) ;;
*) export PATH="/workspace/.devcontainer/bin:/workspace/bin:$PATH" ;;
esac
PROFILE_EOF
# Shortcuts for isolated env switching without memorizing eval commands.
if [ -x /workspace/.devcontainer/install-ssenv-shortcuts.sh ]; then
/workspace/.devcontainer/install-ssenv-shortcuts.sh
fi
# ── 0. Container-level setup (profile.d, shortcuts) ──────────────────
# Delegate to start-dev.sh which handles per-start container init.
# This ensures profile.d scripts exist before any login-shell steps below.
/workspace/.devcontainer/start-dev.sh
# ── 1. Build CLI ────────────────────────────────────────────────────
echo "▸ Building skillshare binary …"
@@ -69,6 +50,9 @@ CFG="$HOME/.config/skillshare"
DEMO="$HOME/demo-project"
/workspace/scripts/create-demo-content.sh "$SKILLS" "$CFG" "$DEMO"
# ── Mark initialisation complete (sentinel on persistent volume) ─────
touch "$HOME/.devcontainer-initialized"
# ── Done ────────────────────────────────────────────────────────────
echo ""
echo "══════════════════════════════════════════════════════════"
+29 -2
View File
@@ -1,8 +1,35 @@
#!/usr/bin/env bash
# Resolve GITHUB_TOKEN and print available commands on container start.
# Per-start container init: profile.d scripts, PATH, token detection.
# Runs on every container start (VS Code postStartCommand / devc.sh).
set -euo pipefail
# Re-assert Linux-safe command entrypoints on every container start.
# ── Profile.d: login-shell environment ───────────────────────────────
# These live on the container filesystem (not volume) and must be
# recreated after container recreation (docker compose down → up).
# Token env: .env overrides host-passed env vars.
cat > /etc/profile.d/skillshare-env.sh << 'PROFILE_EOF'
if [ -f /workspace/.devcontainer/.env ]; then
set -a
. /workspace/.devcontainer/.env
set +a
fi
PROFILE_EOF
# Restore Go toolchain paths (login shell resets PATH, dropping Docker ENV values)
# and keep devcontainer command wrappers ahead of /usr/local/bin.
cat > /etc/profile.d/skillshare-path.sh << 'PROFILE_EOF'
case ":$PATH:" in
*:/usr/local/go/bin:*) ;;
*) export PATH="/go/bin:/usr/local/go/bin:$PATH" ;;
esac
case ":$PATH:" in
*:/workspace/.devcontainer/bin:*) ;;
*) export PATH="/workspace/.devcontainer/bin:/workspace/bin:$PATH" ;;
esac
PROFILE_EOF
# ── Re-assert command entrypoints and shortcuts ──────────────────────
if [ -x /workspace/.devcontainer/ensure-skillshare-linux-binary.sh ]; then
/workspace/.devcontainer/ensure-skillshare-linux-binary.sh
fi
+9 -6
View File
@@ -57,14 +57,18 @@ This also applies to `go test` — tests always compile against the latest sourc
## Entering the Devcontainer
The quickest way to get an interactive shell inside the devcontainer:
The quickest way — one command builds, initialises, and enters the shell:
```bash
make devc # interactive bash shell
./scripts/devcontainer_shell.sh make test # run a command directly
make devc # build + init + interactive shell (one step)
make devc-up # start only (no shell)
make devc-down # stop
make devc-restart # restart + re-run start-dev.sh
make devc-reset # full reset (remove volumes), then `make devc` to re-init
make devc-status # show container status
```
The script auto-detects whether the container is running and prints setup instructions if it isn't.
Works with **or without** VS Code — `make devc` handles the full lifecycle autonomously.
### Programmatic access (for `docker exec` workflows)
@@ -73,8 +77,7 @@ CONTAINER=$(docker compose -f .devcontainer/docker-compose.yml ps -q skillshare-
```
If `$CONTAINER` is empty, tell the user:
> Devcontainer is not running. Please start it with VS Code "Reopen in Container" or run:
> `docker compose -f .devcontainer/docker-compose.yml up -d`
> Devcontainer is not running. Start it with `make devc-up`.
Then verify the binary:
```bash
+23 -3
View File
@@ -1,4 +1,4 @@
.PHONY: help build build-meta build-windows run test test-unit test-int test-docker test-docker-online test-redteam test-redteam-signal test-redteam-rules-signal playground playground-down devc dev-docker dev-docker-down docker-build docker-build-multiarch lint fmt fmt-check check install clean ui-install ui-build ui-dev build-all
.PHONY: help build build-meta build-windows run test test-unit test-int test-docker test-docker-online test-redteam test-redteam-signal test-redteam-rules-signal playground playground-down devc devc-up devc-down devc-restart devc-reset devc-status dev-docker 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:"
@@ -14,7 +14,12 @@ help:
@echo " make test-redteam-rules-signal # verify red team test fails when critical builtin rules are disabled"
@echo " make playground # start playground + enter shell (one step)"
@echo " make playground-down # stop and remove playground"
@echo " make devc # enter running devcontainer shell"
@echo " make devc # start devcontainer + enter shell (one step)"
@echo " make devc-up # start devcontainer (no shell)"
@echo " make devc-down # stop devcontainer"
@echo " make devc-restart # restart devcontainer"
@echo " make devc-reset # full reset (remove volumes)"
@echo " make devc-status # show devcontainer status"
@echo " make lint # go vet"
@echo " make fmt # format Go files"
@echo " make check # fmt-check + lint + test"
@@ -74,7 +79,22 @@ playground-down:
./scripts/sandbox_playground_down.sh
devc:
./scripts/devcontainer_shell.sh
./scripts/devc.sh up && ./scripts/devc.sh shell
devc-up:
./scripts/devc.sh up
devc-down:
./scripts/devc.sh down
devc-restart:
./scripts/devc.sh restart
devc-reset:
./scripts/devc.sh reset
devc-status:
./scripts/devc.sh status
dev-docker:
docker compose -f docker-compose.sandbox.yml --profile dev watch
+9
View File
@@ -29,6 +29,15 @@ RUN apt-get update \
RUN go install github.com/air-verse/air@latest \
&& go install github.com/go-delve/delve/cmd/dlv@latest
# Copy node runtime from ui-builder stage (for devcontainer / interactive use)
COPY --from=ui-builder /usr/local/bin/node /usr/local/bin/
COPY --from=ui-builder /usr/local/lib/node_modules /usr/local/lib/node_modules
RUN ln -sf ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
&& ln -sf ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx \
&& ln -sf ../lib/node_modules/corepack/dist/corepack.js /usr/local/bin/corepack
ARG PNPM_VERSION
RUN npm install -g pnpm@${PNPM_VERSION}
# Copy pre-built frontend for playground UI cache
COPY --from=ui-builder /ui/dist /ui-dist
+31 -3
View File
@@ -16,7 +16,12 @@ echo " mise run test:docker:online # docker online install/update tests"
echo " mise run test:redteam # red team supply-chain security tests"
echo " mise run playground # start playground + enter shell (one step)"
echo " mise run playground:down # stop and remove playground"
echo " mise run devc # enter running devcontainer shell"
echo " mise run devc # start devcontainer + enter shell (one step)"
echo " mise run devc:up # start devcontainer (no shell)"
echo " mise run devc:down # stop devcontainer"
echo " mise run devc:restart # restart devcontainer"
echo " mise run devc:reset # full reset (remove volumes)"
echo " mise run devc:status # show devcontainer status"
echo " mise run lint # go vet"
echo " mise run fmt # format Go files"
echo " mise run check # fmt:check + lint + test"
@@ -87,8 +92,31 @@ description = "Stop and remove playground container"
run = "./scripts/sandbox_playground_down.sh"
[tasks.devc]
description = "Enter running devcontainer shell"
run = "./scripts/devcontainer_shell.sh"
description = "Start devcontainer + enter shell (one step)"
run = """
./scripts/devc.sh up
./scripts/devc.sh shell
"""
[tasks."devc:up"]
description = "Start devcontainer (no shell)"
run = "./scripts/devc.sh up"
[tasks."devc:down"]
description = "Stop devcontainer"
run = "./scripts/devc.sh down"
[tasks."devc:restart"]
description = "Restart devcontainer"
run = "./scripts/devc.sh restart"
[tasks."devc:reset"]
description = "Full reset (remove volumes)"
run = "./scripts/devc.sh reset"
[tasks."devc:status"]
description = "Show devcontainer status"
run = "./scripts/devc.sh status"
[tasks."dev:docker"]
description = "Go API in Docker + auto-rebuild (pair with: cd ui && pnpm run dev)"
+141
View File
@@ -0,0 +1,141 @@
#!/usr/bin/env bash
# Unified devcontainer lifecycle script (no VS Code required).
# Usage: ./scripts/devc.sh <command>
#
# Commands:
# up Start devcontainer (build if needed, run setup on first start)
# shell Enter running devcontainer shell
# down Stop and remove devcontainer
# restart Restart devcontainer
# reset Stop + remove volumes (full reset)
# status Show devcontainer status
# logs Tail devcontainer logs
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
source "$SCRIPT_DIR/_sandbox_common.sh"
COMPOSE_FILE="$PROJECT_ROOT/.devcontainer/docker-compose.yml"
SERVICE="skillshare-devcontainer"
usage() {
echo "Usage: $(basename "$0") <command>"
echo ""
echo "Commands:"
echo " up Start devcontainer (build + init on first run)"
echo " shell Enter running devcontainer shell"
echo " down Stop and remove devcontainer"
echo " restart Restart devcontainer"
echo " reset Stop + remove volumes (full reset)"
echo " status Show devcontainer status"
echo " logs Tail devcontainer logs"
}
# Check if container is running.
is_running() {
local cid
cid="$(docker compose -f "$COMPOSE_FILE" ps -q "$SERVICE" 2>/dev/null || true)"
[[ -n "$cid" ]]
}
# Check if one-time data setup has completed (sentinel on persistent volume).
is_initialised() {
docker compose -f "$COMPOSE_FILE" exec -T "$SERVICE" \
test -f /home/developer/.devcontainer-initialized 2>/dev/null
}
cmd_up() {
require_docker
cd "$PROJECT_ROOT"
echo "▸ Starting devcontainer …"
docker compose -f "$COMPOSE_FILE" up -d --build
if is_initialised; then
echo "▸ Already initialised — running start-dev.sh …"
docker compose -f "$COMPOSE_FILE" exec -T -w /workspace "$SERVICE" \
bash -c '/workspace/.devcontainer/start-dev.sh'
else
echo "▸ First run — running setup.sh …"
docker compose -f "$COMPOSE_FILE" exec -T -w /workspace "$SERVICE" \
bash -c '/workspace/.devcontainer/setup.sh'
fi
}
cmd_shell() {
require_docker
cd "$PROJECT_ROOT"
if ! is_running; then
echo "Devcontainer is not running." >&2
echo "Start it with: make devc-up (or ./scripts/devc.sh up)" >&2
exit 1
fi
docker compose -f "$COMPOSE_FILE" exec -w /workspace "$SERVICE" bash -l
}
cmd_down() {
require_docker
cd "$PROJECT_ROOT"
docker compose -f "$COMPOSE_FILE" down
}
cmd_restart() {
require_docker
cd "$PROJECT_ROOT"
docker compose -f "$COMPOSE_FILE" restart
echo "▸ Running start-dev.sh …"
docker compose -f "$COMPOSE_FILE" exec -T -w /workspace "$SERVICE" \
bash -c '/workspace/.devcontainer/start-dev.sh'
}
cmd_reset() {
require_docker
cd "$PROJECT_ROOT"
docker compose -f "$COMPOSE_FILE" down -v
echo "Volumes removed. Run 'make devc' to re-initialise."
}
cmd_status() {
require_docker
cd "$PROJECT_ROOT"
docker compose -f "$COMPOSE_FILE" ps
}
cmd_logs() {
require_docker
cd "$PROJECT_ROOT"
docker compose -f "$COMPOSE_FILE" logs -f "$SERVICE"
}
if [[ $# -eq 0 ]]; then
usage
exit 1
fi
CMD="$1"
shift
case "$CMD" in
up) cmd_up "$@" ;;
shell) cmd_shell "$@" ;;
down) cmd_down "$@" ;;
restart) cmd_restart "$@" ;;
reset) cmd_reset "$@" ;;
status) cmd_status "$@" ;;
logs) cmd_logs "$@" ;;
help|--help|-h)
usage
;;
*)
echo "Error: unknown command '$CMD'" >&2
echo ""
usage
exit 1
;;
esac
-30
View File
@@ -1,30 +0,0 @@
#!/usr/bin/env bash
# Enter the running devcontainer or execute a command inside it.
# Usage:
# ./scripts/devcontainer_shell.sh # interactive shell
# ./scripts/devcontainer_shell.sh make test # run a command
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
# Reuse require_docker from sandbox common, then override COMPOSE_FILE.
source "$SCRIPT_DIR/_sandbox_common.sh"
require_docker
COMPOSE_FILE="$PROJECT_ROOT/.devcontainer/docker-compose.yml"
SERVICE="skillshare-devcontainer"
if [[ -z "$(docker compose -f "$COMPOSE_FILE" ps -q "$SERVICE" 2>/dev/null || true)" ]]; then
echo "Devcontainer is not running." >&2
echo "Start it with one of:" >&2
echo " 1. VS Code → 'Reopen in Container'" >&2
echo " 2. docker compose -f .devcontainer/docker-compose.yml up -d" >&2
exit 1
fi
if [[ $# -gt 0 ]]; then
docker compose -f "$COMPOSE_FILE" exec -w /workspace "$SERVICE" bash -c "$*"
else
docker compose -f "$COMPOSE_FILE" exec -w /workspace "$SERVICE" bash
fi
+35 -8
View File
@@ -16,7 +16,7 @@ B --> D["Remote-source validation"]
B --> E["Command exploration"]
B --> F["Frontend development"]
B --> G["Deployment / CI"]
B --> H["VS Code / Codespaces"]
B --> H["VS Code / CLI / Codespaces"]
C --> C1["Offline test sandbox"]
C1 --> C2["make test-docker"]
@@ -35,7 +35,7 @@ G1 --> G2["docker-build"]
G1 --> G3["docker/ci/Dockerfile"]
H --> H1["Devcontainer"]
H1 --> H2["Reopen in Container"]
H1 --> H2["make devc / Reopen in Container"]
```
Command mapping:
@@ -47,6 +47,12 @@ Command mapping:
| **Playground** (start + shell) | **`mise run playground`** | **`make playground`** |
| Playground (stop) | `mise run playground:down` | `make playground-down` |
| Sandbox (advanced) | — | `./scripts/sandbox.sh <up\|down\|shell\|reset\|status\|logs\|bare>` |
| **Devcontainer** (start + shell) | **`mise run devc`** | **`make devc`** |
| Devcontainer (start only) | `mise run devc:up` | `make devc-up` |
| Devcontainer (stop) | `mise run devc:down` | `make devc-down` |
| Devcontainer (restart) | `mise run devc:restart` | `make devc-restart` |
| Devcontainer (full reset) | `mise run devc:reset` | `make devc-reset` |
| Devcontainer (status) | `mise run devc:status` | `make devc-status` |
| Dev API server | `mise run dev:docker` | `make dev-docker` |
| Dev stop | `mise run dev:docker:down` | `make dev-docker-down` |
| Docker build | `mise run docker:build` | `make docker-build` |
@@ -255,18 +261,19 @@ Both approaches give you instant HMR for `ui/` changes. The Docker variant pins
---
## Devcontainer (VS Code / Codespaces)
## Devcontainer (VS Code / Codespaces / CLI)
Open the project in a ready-to-code container — no local Go, Node, or pnpm needed.
Open the project in a ready-to-code container — no local Go, Node, or pnpm needed. Works with **or without** VS Code.
:::info Devcontainer vs Playground
Both use the same base image and demo content. The **playground** (`make playground`) is a terminal-only environment for exploring commands. The **devcontainer** adds VS Code integration (IntelliSense, debugger, extensions) for developing the skillshare codebase itself.
Both use the same base image and demo content. The **playground** (`make playground`) is a terminal-only environment for exploring commands. The **devcontainer** adds development tooling (Go, Node, pnpm, air) for developing the skillshare codebase itself — usable from VS Code, Codespaces, or a plain terminal.
:::
### Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) running
- VS Code with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension installed
- **Option A (terminal):** No extra tools needed — `make devc` handles everything
- **Option B (VS Code):** VS Code with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension installed
:::tip GitHub Codespaces
On GitHub, click **Code → Codespaces → New codespace**. The devcontainer config is picked up automatically — no local Docker or extension needed.
@@ -274,6 +281,26 @@ On GitHub, click **Code → Codespaces → New codespace**. The devcontainer con
### Getting started
**From terminal** (no VS Code required):
```bash
make devc # build image → start container → setup → enter shell
```
First run takes a few minutes (building image, installing deps). Subsequent runs detect the existing setup and skip straight to the shell.
Other lifecycle commands:
```bash
make devc-up # start only (no shell)
make devc-down # stop container
make devc-restart # restart + re-run start-dev.sh
make devc-reset # full reset (remove volumes), then make devc to re-init
make devc-status # show container status
```
**From VS Code:**
1. Open the project folder in VS Code
2. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) and select **Dev Containers: Reopen in Container**
3. Wait for the container to build (first time takes a few minutes, subsequent opens are fast)
@@ -284,7 +311,7 @@ On GitHub, click **Code → Codespaces → New codespace**. The devcontainer con
The devcontainer reuses the same `docker/sandbox/Dockerfile` as the sandbox, so you get:
- Go 1.25 toolchain
- Node.js 24 + pnpm (via [devcontainer feature](https://github.com/devcontainers/features/tree/main/src/node)) — enables `make ui-dev` and `cd website && pnpm start` inside the container
- Node.js 24 + pnpm (bundled in the Docker image) — enables `make ui-dev` and `cd website && pnpm start` inside the container
- VS Code extensions: Go, Tailwind CSS, ESLint, Prettier
- Ports forwarded: `19420` (Web UI), `5173` (Vite HMR), `3000` (Docusaurus)
- Source code mounted at `/workspace`
@@ -471,7 +498,7 @@ Browse published versions at [GitHub Packages](https://github.com/runkids/skills
- **Playground and dev profile share port 19420** — run only one at a time. Stop the other first (`make playground-down` or `make dev-docker-down`).
- Offline sandbox cannot validate network-dependent features (for example remote `install` from GitHub).
- Playground uses container-local `HOME`, so it does not directly modify your real host home config.
- Go code changes are picked up automatically (`go build` runs inside the container from mounted source). **Frontend (`ui/`) changes** are picked up instantly when running `make ui-dev` (Vite HMR) inside the devcontainer. For the playground, run `make ui-build` on the host first since the playground container does not include Node.js.
- Go code changes are picked up automatically (`go build` runs inside the container from mounted source). **Frontend (`ui/`) changes** are picked up instantly when running `make ui-dev` (Vite HMR) inside the devcontainer. Both devcontainer and playground include Node.js and pnpm.
- If you need custom experiments, pass commands directly:
```bash