dock

Self-hosted server platform — a dashboard and reverse proxy for your own server, in a single binary. Deploy a Docker image, get an HTTPS subdomain automatically. Watch OS + image updates and apply them from the UI. Drive the whole thing from Claude over MCP.

Go API + Astro/Vue frontend, with Traefik v3 as the routing backbone. UI identity: dockd — netrunner-brutalist (near-black, yellow/red/cyan channels, mono data, sharp corners).

---

What it does

• Deploy = image + name. dock creates the container on the edge network with Traefik labels (Host(<name>.example.com)); a wildcard cert covers it, so it's reachable over HTTPS in seconds — no proxy config, no DNS change. Non-HTTP apps get a host port from a 31000–31999 allocator instead.
• Manage containers. Unified list (compose-stack aware), start/stop/restart, live log follow, 1 Hz stats with sparklines — all over WebSocket. A protected-container guard keeps you from stopping Traefik or dock itself.
• Updates & notifications. A host-side dock-agent reports apt/dnf upgrades and reboot-required; dock checks registry digests for running images. Apply OS upgrades (streamed terminal) or per-app image updates (pull → recreate → rollback on failure) from the UI. Optional Matrix / ntfy notifier with a background watcher.
• MCP server. dock exposes its management API over the Model Context Protocol (streamable HTTP at /mcp, scoped bearer tokens) — 16 tools so Claude Code/Desktop can deploy apps, control containers, read logs, and run updates. See docs/mcp.md.
• Auth. First-boot /setup?token=… URL (no default password), argon2id login, sliding sessions, CSRF header, rate-limited. dock's own UI can be restricted to LAN + VPN ranges at the Traefik layer, since it wields root-equivalent power.

Architecture

Internet ──▶ router 80/443 ─────────────▶ Traefik (edge network)
LAN ──DNS *.example.com──▶ host ────────▶ Traefik
                                            │ docker provider (labels) → app containers
                                            │ file provider → host-network apps
dock UI (server.example.com) ── Go API ──▶ /var/run/docker.sock  (deploys w/ traefik labels)
                                └──────────▶ dock-agent (host systemd, localhost) → apt/dnf, reboot

Full topology, request flows, and the security model: docs/architecture.md.

Tech stack

Layer	Choice
Backend	Go 1.25 — chi router, Docker SDK (moby/moby/client), modernc.org/sqlite (pure Go, no CGO)
Auth	argon2id (x/crypto), opaque session tokens, token-bucket limiter
MCP	modelcontextprotocol/go-sdk v1.6, streamable HTTP
Agent	Separate Go module, dependency-tiny, apt + dnf backends (auto-detected via /etc/os-release)
Frontend	Astro 5 (SPA view transitions) + Vue 3 islands + Tailwind 4, embedded in the binary via go:embed
Proxy	Traefik v3 — Docker-label discovery, wildcard Let's Encrypt via Cloudflare DNS-01
Ship	Multi-stage distroless image (~26 MB), Forgejo Actions CI → Forgejo container registry

Repository layout

dock/
├── PLAN.md · docs/                 # roadmap + detailed design (index in PLAN.md)
├── backend/                        # Go API (go:embed's the frontend). module: …/dock/backend
├── agent/                          # dock-agent — separate module, kept tiny
├── frontend/                       # Astro + Vue (dockd design system)
├── deploy/                         # prod compose, Traefik templates, agent systemd unit + installer
├── Dockerfile                      # multi-stage, distroless
└── .forgejo/workflows/ci.yml       # test → build-push → deploy

Quick start (dev mode)

Everything server-only is simulatable on a laptop — a mock agent, fake or real Docker, *.dock.localtest.me routing. No server required.

make dev          # builds backend + agent, runs mock dock-agent + dock in DOCK_MODE=dev

In another terminal, for the frontend with hot reload (proxies /api to :8080):

cd frontend && npm install && npm run dev

First run prints a one-time /setup?token=… URL — open it to create the admin login. Optional: make dev-traefik brings up a dev Traefik for real *.dock.localtest.me routing (needs Docker). Full details: docs/dev-mode.md.

Common targets: make test (backend + agent), make image (production build), make agent-linux (static agent binary for the host).

Build & deploy

Production is a single distroless container (frontend embedded) behind Traefik, published to a container registry by CI and deployed to /opt/dock/ on the host. Repo layout, Dockerfile, compose, CI/CD, and secrets: docs/deploy.md. Backups, rollback, and the verification matrix: docs/operations.md.

Documentation

PLAN.md is the forward-looking roadmap and stays short; the detailed design lives in docs/:

Doc	Contents
architecture.md	Topology, request flows, security model, failure modes
traefik.md	Traefik v3 config: static + file-provider routes, middlewares, cert resolver
backend.md	Go API: package layout, REST/WS spec, SQLite schema, deploy pipeline, auth
frontend.md	Astro + Vue UI: dockd design language, wireframes, components
agent.md	dock-agent: host API, apt/dnf integration, streamed upgrades, systemd unit
mcp.md	MCP server: endpoint, API tokens & scopes, tool catalog, client setup
dev-mode.md	Dev/test mode: mock agent, fake Docker, localtest.me routing
deploy.md	Repo layout, Dockerfile, compose, Forgejo Actions CI/CD, registry, secrets
operations.md	Runbook: backups, adding apps, troubleshooting, rollback, notifications setup

License

MIT.