refactor(devcontainer): simplify dev server management

Replace dev-servers with self-contained `ui` and `docs` commands:
- `ui` / `ui -p`: build binary, start API (global/project) + Vite
- `ui stop`: stop API + Vite
- `docs` / `docs stop`: start/stop Docusaurus
- Remove `ui-p` script (merged into `ui -p`)
- Fix PID reuse false-positive in is_running() via /proc/cmdline
- Fix process tree cleanup in do_stop() (kill children before parent)
- Fix pkill pattern to match `skillshare-dev` binary name
- Update devcontainer.json port labels and ordering
- Update docker-sandbox.md to reflect new commands
This commit is contained in:
Willie
2026-02-20 22:13:33 +08:00
parent be9ac8945c
commit 595fe84c6b
8 changed files with 388 additions and 122 deletions
+69 -7
View File
@@ -1,9 +1,71 @@
#!/bin/sh
# Devcontainer: ensure Docusaurus dev server is running, then print URL.
URL="http://localhost:3000"
#!/usr/bin/env bash
# Devcontainer: start/stop Docusaurus.
# Usage: docs # start → http://localhost:3000
# docs stop # stop
set -euo pipefail
if ! curl -sf "$URL" >/dev/null 2>&1; then
dev-servers start docusaurus
sleep 2
PORT=3000
PIDDIR=/tmp/dev-servers
LOGDIR=/tmp
mkdir -p "$PIDDIR"
# Resolve pnpm
PNPM_BIN=""
if command -v pnpm >/dev/null 2>&1; then
PNPM_BIN="$(command -v pnpm)"
elif [ -x /usr/local/share/pnpm/pnpm ]; then
PNPM_BIN="/usr/local/share/pnpm/pnpm"
elif [ -x /usr/local/bin/pnpm ]; then
PNPM_BIN="/usr/local/bin/pnpm"
elif [ -x /usr/local/share/nvm/current/bin/pnpm ]; then
PNPM_BIN="/usr/local/share/nvm/current/bin/pnpm"
fi
echo "✓ Docs: $URL"
is_port_open() {
timeout 1 bash -c "echo > /dev/tcp/127.0.0.1/$1" 2>/dev/null
}
kill_pid_file() {
local pf="$1"
[ -f "$pf" ] || return 0
local pid; pid=$(cat "$pf")
pkill -P "$pid" 2>/dev/null || true
kill "$pid" 2>/dev/null || true
sleep 0.3
kill -9 "$pid" 2>/dev/null || true
rm -f "$pf"
}
case "${1:-start}" in
stop)
kill_pid_file "$PIDDIR/docusaurus.pid"
fuser -k $PORT/tcp 2>/dev/null || true
echo " docusaurus stopped"
;;
*)
if is_port_open $PORT; then
echo "✓ Docs: http://localhost:$PORT (run 'docs stop' to shut down)"
exit 0
fi
if [ -z "$PNPM_BIN" ]; then
echo " docusaurus failed: pnpm not found" >&2
exit 1
fi
if [ ! -x /workspace/website/node_modules/.bin/docusaurus ]; then
(cd /workspace/website && "$PNPM_BIN" install --frozen-lockfile > "$LOGDIR/docusaurus-deps.log" 2>&1) || true
fi
(cd /workspace/website && nohup "$PNPM_BIN" exec docusaurus start --host 0.0.0.0 --port $PORT --no-open > "$LOGDIR/docusaurus-dev.log" 2>&1 &
echo $! > "$PIDDIR/docusaurus.pid")
for _ in $(seq 1 60); do
is_port_open $PORT && break
sleep 1
done
if is_port_open $PORT; then
echo "✓ Docs: http://localhost:$PORT (run 'docs stop' to shut down)"
else
echo " docusaurus failed to start (see $LOGDIR/docusaurus-dev.log)" >&2
tail -n 10 "$LOGDIR/docusaurus-dev.log" 2>/dev/null | sed 's/^/ /' >&2
exit 1
fi
;;
esac
+109 -12
View File
@@ -1,17 +1,114 @@
#!/bin/sh
# Devcontainer: switch to global-mode API and open dashboard.
URL="http://localhost:19420"
#!/usr/bin/env bash
# Devcontainer: launch dashboard (API backend + Vite frontend).
# Usage: ui # global mode → http://localhost:5173
# ui -p # project mode (~/demo-project) → http://localhost:5173
# ui stop # stop API + Vite
set -euo pipefail
# Already running in global mode via dev-servers? Just print URL.
if [ -f /tmp/dev-servers/api.pid ] && kill -0 "$(cat /tmp/dev-servers/api.pid)" 2>/dev/null; then
echo "✓ Dashboard (global): $URL"
PORT=19420
VITE_PORT=5173
PIDDIR=/tmp/dev-servers
LOGDIR=/tmp
mkdir -p "$PIDDIR"
# Resolve pnpm
PNPM_BIN=""
if command -v pnpm >/dev/null 2>&1; then
PNPM_BIN="$(command -v pnpm)"
elif [ -x /usr/local/share/pnpm/pnpm ]; then
PNPM_BIN="/usr/local/share/pnpm/pnpm"
elif [ -x /usr/local/bin/pnpm ]; then
PNPM_BIN="/usr/local/bin/pnpm"
elif [ -x /usr/local/share/nvm/current/bin/pnpm ]; then
PNPM_BIN="/usr/local/share/nvm/current/bin/pnpm"
fi
is_port_open() {
timeout 1 bash -c "echo > /dev/tcp/127.0.0.1/$1" 2>/dev/null
}
kill_pid_file() {
local pf="$1"
[ -f "$pf" ] || return 0
local pid; pid=$(cat "$pf")
pkill -P "$pid" 2>/dev/null || true
kill "$pid" 2>/dev/null || true
sleep 0.3
kill -9 "$pid" 2>/dev/null || true
rm -f "$pf"
}
# Parse args
MODE="global"
ACTION="start"
for arg in "$@"; do
case "$arg" in
-p|--project) MODE="project" ;;
-g|--global) MODE="global" ;;
stop) ACTION="stop" ;;
esac
done
# ── stop ──
if [ "$ACTION" = "stop" ]; then
kill_pid_file "$PIDDIR/api.pid"
pkill -f 'skillshare.* ui' 2>/dev/null || true
fuser -k $PORT/tcp 2>/dev/null || true
kill_pid_file "$PIDDIR/vite.pid"
fuser -k $VITE_PORT/tcp 2>/dev/null || true
echo " api + vite stopped"
exit 0
fi
# Kill project-mode server if running.
pkill -f 'skillshare ui -p --host' 2>/dev/null || true
sleep 0.5
# ── start ──
# Start global mode via dev-servers (background).
dev-servers start api
echo "✓ Dashboard (global): $URL"
# Stop old API.
kill_pid_file "$PIDDIR/api.pid"
pkill -f 'skillshare.* ui' 2>/dev/null || true
fuser -k $PORT/tcp 2>/dev/null || true
for _ in 1 2 3 4 5 6; do
is_port_open $PORT || break
sleep 0.5
done
# Build binary.
printf " %-12s building..." "api"
if ! (cd /workspace && /usr/local/go/bin/go build -o /tmp/skillshare-dev ./cmd/skillshare) 2>"$LOGDIR/ui-build.log"; then
echo " failed (see $LOGDIR/ui-build.log)"
exit 1
fi
echo " ok"
# Start API.
if [ "$MODE" = "project" ]; then
cd ~/demo-project
fi
nohup /tmp/skillshare-dev ui "-${MODE:0:1}" --no-open --host 0.0.0.0 --port $PORT > "$LOGDIR/api-dev.log" 2>&1 &
echo $! > "$PIDDIR/api.pid"
printf " %-12s started (%s mode)\n" "api" "$MODE"
# Ensure Vite is running.
if is_port_open $VITE_PORT; then
printf " %-12s already running (port %s)\n" "vite" "$VITE_PORT"
else
if [ -z "$PNPM_BIN" ]; then
echo " vite skipped: pnpm not found" >&2
else
if [ ! -x /workspace/ui/node_modules/.bin/vite ]; then
(cd /workspace/ui && "$PNPM_BIN" install --frozen-lockfile > "$LOGDIR/vite-deps.log" 2>&1) || true
fi
(cd /workspace/ui && nohup "$PNPM_BIN" exec vite --host 0.0.0.0 --port $VITE_PORT --strictPort > "$LOGDIR/vite-dev.log" 2>&1 &
echo $! > "$PIDDIR/vite.pid")
for _ in $(seq 1 20); do
is_port_open $VITE_PORT && break
sleep 0.5
done
if is_port_open $VITE_PORT; then
printf " %-12s started (port %s)\n" "vite" "$VITE_PORT"
else
printf " %-12s failed to start (see %s/vite-dev.log)\n" "vite" "$LOGDIR" >&2
fi
fi
fi
echo "✓ Dashboard ($MODE): http://localhost:$VITE_PORT"
-14
View File
@@ -1,14 +0,0 @@
#!/bin/sh
# Devcontainer: switch to project-mode API and open dashboard.
URL="http://localhost:19420"
# Stop global-mode API.
dev-servers stop api 2>/dev/null || true
# Stop any existing project-mode server.
pkill -f 'skillshare ui -p --host' 2>/dev/null || true
sleep 0.5
echo "▸ Starting project-mode API (Ctrl-C to stop)"
echo " Dashboard: $URL"
cd ~/demo-project && exec go run /workspace/cmd/skillshare ui -p --host 0.0.0.0 "$@"
+155 -16
View File
@@ -12,18 +12,95 @@ if [ "${BASH_VERSINFO[0]}" -lt 4 ]; then
exit 1
fi
PNPM_BIN=""
if command -v pnpm >/dev/null 2>&1; then
PNPM_BIN="$(command -v pnpm)"
elif [ -x /usr/local/share/pnpm/pnpm ]; then
PNPM_BIN="/usr/local/share/pnpm/pnpm"
elif [ -x /usr/local/bin/pnpm ]; then
PNPM_BIN="/usr/local/bin/pnpm"
elif [ -x /usr/local/share/nvm/current/bin/pnpm ]; then
PNPM_BIN="/usr/local/share/nvm/current/bin/pnpm"
fi
declare -A PORTS=([api]=19420 [vite]=5173 [docusaurus]=3000)
declare -A DIRS=([api]=/workspace [vite]=/workspace/ui [docusaurus]=/workspace/website)
declare -A CMDS=(
[api]="go run ./cmd/skillshare ui --no-open --host 0.0.0.0"
[vite]="pnpm run dev"
[docusaurus]="pnpm start --host 0.0.0.0"
[api]="/usr/local/go/bin/go run ./cmd/skillshare ui --no-open --host 0.0.0.0 --port 19420"
[vite]="${PNPM_BIN:-pnpm} exec vite --host 0.0.0.0 --port 5173 --strictPort"
[docusaurus]="${PNPM_BIN:-pnpm} exec docusaurus start --host 0.0.0.0 --port 3000 --no-open"
)
ALL=(api vite docusaurus)
declare -A VERIFY=([api]="skillshare" [vite]="vite" [docusaurus]="docusaurus")
ALL=(vite docusaurus)
is_running() {
local pf="$PIDDIR/$1.pid"
[ -f "$pf" ] && kill -0 "$(cat "$pf")" 2>/dev/null
local n="$1" pf="$PIDDIR/$1.pid"
[ -f "$pf" ] || return 1
local pid
pid=$(cat "$pf")
kill -0 "$pid" 2>/dev/null || { rm -f "$pf"; return 1; }
# Guard against PID reuse: verify cmdline contains expected keyword
if [ -r "/proc/$pid/cmdline" ]; then
tr '\0' ' ' < "/proc/$pid/cmdline" | grep -qi "${VERIFY[$n]}" || { rm -f "$pf"; return 1; }
fi
}
is_port_open() {
local port="$1"
timeout 1 bash -c "echo > /dev/tcp/127.0.0.1/$port" >/dev/null 2>&1
}
wait_for_port() {
local port="$1"
# Wait up to ~60s (webpack/docusaurus first boot can be slow).
for _ in $(seq 1 120); do
if is_port_open "$port"; then
return 0
fi
sleep 0.5
done
return 1
}
ensure_api_initialized() {
local cfg="$HOME/.config/skillshare/config.yaml"
if [ -f "$cfg" ]; then
return 0
fi
(
cd /workspace
/usr/local/go/bin/go run ./cmd/skillshare init -g --no-copy --all-targets --no-git --skill >/tmp/api-init.log 2>&1
)
}
ensure_frontend_deps() {
local n="$1"
local dir="${DIRS[$n]}"
local bin=""
local dep_log="$LOGDIR/${n}-deps.log"
case "$n" in
vite) bin="$dir/node_modules/.bin/vite" ;;
docusaurus) bin="$dir/node_modules/.bin/docusaurus" ;;
*) return 0 ;;
esac
if [ -x "$bin" ]; then
return 0
fi
(
cd "$dir"
"$PNPM_BIN" install --frozen-lockfile >"$dep_log" 2>&1
)
}
print_failure_tail() {
local n="$1"
local log="$LOGDIR/${n}-dev.log"
if [ -f "$log" ]; then
echo " Last log lines ($log):" >&2
tail -n 20 "$log" | sed 's/^/ /' >&2
fi
}
validate_target() {
@@ -36,18 +113,51 @@ validate_target() {
do_start() {
local n=$1
if is_running "$n"; then
printf " %-12s already running (port %s)\n" "$n" "${PORTS[$n]}"
return
if { [ "$n" = "vite" ] || [ "$n" = "docusaurus" ]; } && [ -z "$PNPM_BIN" ]; then
printf " %-12s failed: pnpm not found in PATH\n" "$n" >&2
return 1
fi
if [ "$n" = "api" ] && ! ensure_api_initialized; then
printf " %-12s bootstrap failed (see /tmp/api-init.log)\n" "$n" >&2
if [ -f /tmp/api-init.log ]; then
tail -n 20 /tmp/api-init.log | sed 's/^/ /' >&2
fi
return 1
fi
if { [ "$n" = "vite" ] || [ "$n" = "docusaurus" ]; } && ! ensure_frontend_deps "$n"; then
printf " %-12s dependency bootstrap failed (see %s/%s-deps.log)\n" "$n" "$LOGDIR" "$n" >&2
if [ -f "$LOGDIR/${n}-deps.log" ]; then
tail -n 20 "$LOGDIR/${n}-deps.log" | sed 's/^/ /' >&2
fi
return 1
fi
if ! is_running "$n" && is_port_open "${PORTS[$n]}"; then
printf " %-12s port %s already in use (unmanaged process)\n" "$n" "${PORTS[$n]}"
return 0
fi
( cd "${DIRS[$n]}" && nohup ${CMDS[$n]} > "$LOGDIR/${n}-dev.log" 2>&1 & echo $! > "$PIDDIR/${n}.pid" )
sleep 0.3
if is_running "$n"; then
if is_port_open "${PORTS[$n]}"; then
printf " %-12s already running (port %s)\n" "$n" "${PORTS[$n]}"
return
fi
printf " %-12s running (PID %s) but port %s is not reachable; restarting\n" "$n" "$(cat "$PIDDIR/${n}.pid")" "${PORTS[$n]}"
do_stop "$n"
fi
(
cd "${DIRS[$n]}"
nohup bash -lc "${CMDS[$n]}" > "$LOGDIR/${n}-dev.log" 2>&1 &
echo $! > "$PIDDIR/${n}.pid"
)
if is_running "$n" && wait_for_port "${PORTS[$n]}"; then
printf " %-12s started → http://localhost:%s\n" "$n" "${PORTS[$n]}"
return
fi
if is_running "$n"; then
kill "$(cat "$PIDDIR/${n}.pid")" 2>/dev/null || true
fi
rm -f "$PIDDIR/${n}.pid"
printf " %-12s failed to start (see %s/%s-dev.log)\n" "$n" "$LOGDIR" "$n" >&2
print_failure_tail "$n"
return 1
}
@@ -59,12 +169,17 @@ do_stop() {
return
fi
local pid; pid=$(cat "$pf")
# Kill children first (go run → compiled binary), then wrapper bash.
pkill -P "$pid" 2>/dev/null || true
kill "$pid" 2>/dev/null || true
for _ in 1 2 3 4 5; do
kill -0 "$pid" 2>/dev/null || break
sleep 0.2
done
pkill -9 -P "$pid" 2>/dev/null || true
kill -9 "$pid" 2>/dev/null || true
# Last resort: free the port directly.
fuser -k "${PORTS[$n]}/tcp" 2>/dev/null || true
rm -f "$pf"
printf " %-12s stopped\n" "$n"
}
@@ -72,7 +187,13 @@ do_stop() {
do_status() {
local n=$1
if is_running "$n"; then
printf " %-12s ✓ running port %-5s PID %s\n" "$n" "${PORTS[$n]}" "$(cat "$PIDDIR/$n.pid")"
if is_port_open "${PORTS[$n]}"; then
printf " %-12s ✓ running port %-5s PID %s\n" "$n" "${PORTS[$n]}" "$(cat "$PIDDIR/$n.pid")"
else
printf " %-12s ! running port %-5s unreachable PID %s\n" "$n" "${PORTS[$n]}" "$(cat "$PIDDIR/$n.pid")"
fi
elif is_port_open "${PORTS[$n]}"; then
printf " %-12s ~ listening port %-5s (unmanaged)\n" "$n" "${PORTS[$n]}"
else
printf " %-12s ✗ stopped\n" "$n"
rm -f "$PIDDIR/$n.pid"
@@ -88,13 +209,31 @@ targets() {
fi
}
start_targets() {
local failed=0
local t="$1"
for n in $(targets "$t"); do
if ! do_start "$n"; then
failed=1
fi
done
return $failed
}
stop_targets() {
local t="$1"
for n in $(targets "$t"); do
do_stop "$n"
done
}
case "${1:-help}" in
start) for n in $(targets "${2:-}"); do do_start "$n"; done ;;
stop) for n in $(targets "${2:-}"); do do_stop "$n"; done ;;
start) start_targets "${2:-}" ;;
stop) stop_targets "${2:-}" ;;
restart)
for n in $(targets "${2:-}"); do do_stop "$n"; done
stop_targets "${2:-}"
sleep 1
for n in $(targets "${2:-}"); do do_start "$n"; done
start_targets "${2:-}"
;;
status) for n in $(targets "${2:-}"); do do_status "$n"; done ;;
logs)
+4 -4
View File
@@ -9,11 +9,11 @@
"pnpmVersion": "10.28.0"
}
},
"forwardPorts": [19420, 5173, 3000],
"forwardPorts": [5173, 19420, 3000],
"portsAttributes": {
"19420": { "label": "API Server" },
"5173": { "label": "Vite (UI)" },
"3000": { "label": "Docusaurus" }
"5173": { "label": "Dashboard (ui)" },
"19420": { "label": "API Backend" },
"3000": { "label": "Docs (docs)" }
},
"remoteEnv": {
"PATH": "/workspace/.devcontainer/bin:/workspace/bin:${containerEnv:PATH}",
+13 -10
View File
@@ -27,12 +27,18 @@ echo "▸ Installing website dependencies …"
# survives make clean). Only ephemeral symlinks are created here.
echo "▸ Installing shortcut commands …"
ln -sf /workspace/bin/skillshare /workspace/bin/ss
ln -sf /workspace/.devcontainer/dev-servers.sh /workspace/.devcontainer/bin/dev-servers
# ── 3. Global mode init ────────────────────────────────────────────
echo "▸ Initializing global mode …"
mkdir -p "$HOME/.claude/skills"
skillshare init -g --no-copy --all-targets --no-git --skill
GLOBAL_CFG="$HOME/.config/skillshare/config.yaml"
if [ -f "$GLOBAL_CFG" ]; then
echo " ✓ Already initialized ($GLOBAL_CFG), skipping init"
elif skillshare status >/dev/null 2>&1; then
echo " ✓ Already initialized (detected via 'skillshare status'), skipping init"
else
skillshare init -g --no-copy --all-targets --no-git --skill
fi
# ── 4. Create demo content (shared with sandbox playground) ───────
echo "▸ Creating demo content …"
@@ -50,14 +56,11 @@ echo ""
echo "Quick start:"
echo " ss status # check current state"
echo " ss list # see all skills"
echo " ui # global-mode dashboard (auto-started)"
echo " ui-p # switch to project-mode dashboard"
echo " docs # open documentation site"
echo ""
echo "Dev servers (auto-started on container open):"
echo " dev-servers status # check which servers are running"
echo " dev-servers restart # restart all dev servers"
echo " dev-servers logs vite # tail Vite log (api|vite|docusaurus)"
echo " ui # global-mode dashboard → :5173"
echo " ui -p # project-mode dashboard → :5173"
echo " ui stop # stop dashboard"
echo " docs # documentation site → :3000"
echo " docs stop # stop docs"
echo ""
echo "Audit playground:"
echo " ss audit # scan all skills, see findings"
+9 -3
View File
@@ -1,4 +1,10 @@
#!/usr/bin/env bash
# Auto-start dev servers when devcontainer starts.
# Delegates to dev-servers manager for process tracking.
exec /workspace/.devcontainer/dev-servers.sh start
# Print available commands on container start.
set -euo pipefail
echo "Dev servers ready:"
echo " ui # global-mode dashboard → :5173"
echo " ui -p # project-mode dashboard → :5173"
echo " ui stop # stop dashboard"
echo " docs # documentation site → :3000"
echo " docs stop # stop docs"
+29 -56
View File
@@ -44,6 +44,7 @@ Command mapping:
|---|---|---|
| `test-docker` | `mise run test:docker` | `make test-docker` |
| `test-docker-online` | `mise run test:docker:online` | `make test-docker-online` |
| **`playground`** | **`mise run playground`** | **`make playground`** |
| `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` |
@@ -91,13 +92,19 @@ mise run test:docker:online
make test-docker-online
```
### 3. Open a dedicated playground and explore all commands
### 3. Open a dedicated playground and explore all commands {#playground}
One command to start and enter the playground:
```bash
mise run sandbox:up
mise run sandbox:shell
make sandbox-up
make sandbox-shell
make playground
mise run playground
```
Or start and enter separately:
```bash
make sandbox-up && make sandbox-shell
```
Inside the playground, `skillshare` and `ss` are ready. Both global mode and project mode are pre-initialized:
@@ -119,31 +126,14 @@ skillshare list
skillshare sync --dry-run
```
To launch the project mode web dashboard, use the built-in alias:
To launch the web dashboard, use the built-in aliases:
```bash
skillshare-ui-p # starts project mode dashboard on port 19420
skillshare-ui # global mode dashboard → http://localhost:19420
skillshare-ui-p # project mode dashboard (~/demo-project) → http://localhost:19420
```
Or run the command manually from the demo project directory:
```bash
cd ~/demo-project
skillshare ui -p --host 0.0.0.0 --no-open
```
Then open `http://localhost:19420` on your host machine.
### Web UI in the Playground
The playground container includes pre-built frontend assets and maps port 19420 to the host. Both global and project mode are pre-initialized, so you can launch the dashboard immediately:
```bash
skillshare-ui # global mode dashboard
skillshare-ui-p # project mode dashboard (~/demo-project)
```
Then open `http://localhost:19420` in your host browser. Use `--host 0.0.0.0` because the container's `127.0.0.1` is not reachable from the host.
Then open `http://localhost:19420` on your host machine (port is mapped via Docker Compose).
### GitHub Token (for Search)
@@ -323,7 +313,7 @@ The devcontainer reuses the same `docker/sandbox/Dockerfile` as the sandbox, so
- Ports forwarded: `19420` (Web UI), `5173` (Vite HMR), `3000` (Docusaurus)
- Source code mounted at `/workspace`
- **Pre-configured demo environment** — same as the interactive playground:
- Shortcut commands in PATH (`ss`, `ui`, `ui-p`, `docs`, `dev-servers`)
- Shortcut commands in PATH (`ss`, `ui`, `docs`)
- Frontend dependencies pre-installed (`ui/` and `website/`)
- Global demo skills (audit examples, deploy checklist)
- Custom audit rules (global + project)
@@ -339,43 +329,26 @@ ss audit # run audit with custom rules
cd ~/demo-project
ss status # auto-detects project mode
ss audit # project-level audit
ui-p # switch to project mode dashboard (:19420)
ui -p # switch API to project mode → http://localhost:5173
```
### Frontend development
All three dev servers start automatically when the container opens:
| Port | Service | What it serves |
|------|---------|----------------|
| `19420` | Go API server | REST API backend |
| `5173` | Vite | React UI with hot reload |
| `3000` | Docusaurus | Documentation site with hot reload |
Open `http://localhost:5173` (UI) or `http://localhost:3000` (docs) in your host browser — they're ready immediately.
These URLs are available via Dev Containers port forwarding (no fixed host port bind in `.devcontainer/docker-compose.yml`).
**Managing dev servers:**
| Port | Service | Command |
|------|---------|---------|
| `5173` | Vite (React UI + HMR) | `ui` or `ui -p` |
| `19420` | Go API backend | started by `ui` / `ui -p` |
| `3000` | Docusaurus | `docs` |
```bash
dev-servers status # check which servers are running
dev-servers restart # restart all
dev-servers restart vite # restart just Vite
dev-servers stop docusaurus # stop just Docusaurus
dev-servers logs api # tail Go API server log
ui # global mode: API + Vite → http://localhost:5173
ui -p # project mode: API + Vite → http://localhost:5173
ui stop # stop API + Vite
docs # documentation site → http://localhost:3000
docs stop # stop Docusaurus
```
Servers shut down automatically when the container stops and restart on the next container start.
### Running the Web UI inside the container
```bash
ui # global mode dashboard (auto-started by dev-servers)
ui-p # switch to project mode (stops global, Ctrl-C to return)
docs # open documentation site (:3000)
# VS Code auto-forwards port 19420 → open http://localhost:19420
```
`ui` starts both the Go API backend (port 19420, background) and Vite dev server (port 5173, HMR). Switching between `ui` and `ui -p` automatically restarts the API in the new mode. VS Code auto-forwards ports to your host browser.
### Running tests