This walks through a single Capstan instance end to end: bring it up, create the admin account, and use the dashboard to create and start your first stack. It assumes you've already read the README's Quick Start — this is the tutorial that starts where that leaves off.
Verified against Capstan version dev (commit unknown, no build date) —
this instance was built from source rather than a tagged release, so
Settings → About and GET /api/v1/version both report dev instead of a
version number. If you're running a published image, About will show a real
version tag instead. The walkthrough landed in commit a20b9f1 (2026-08-07);
diff docs/, frontend/ and backend/ from there to see what may have
drifted since.
STACKS_DIR controls where stack directories are written, both inside and
outside the container — the two paths must match. The default is
/opt/stacks, and the container deliberately never takes ownership of
it: docker/entrypoint.sh remaps its runtime user to PUID/PGID
(default 1000:1000) instead of chowning the directory, specifically so
Capstan never rewrites ownership of compose projects that already live
there. On a host where /opt/stacks doesn't already belong to that user —
including a plain default install where nothing has claimed it yet — the
first stack you create will fail with a directory error, and the error
doesn't say why.
Avoid that by pointing STACKS_DIR at a directory you own before you start:
mkdir -p ~/capstan-stacksIf you'd rather use /opt/stacks (or another shared path), align
PUID/PGID to its owner instead — see
Paths, volumes & container user.
From the repository root:
STACKS_DIR=~/capstan-stacks docker compose up -d --buildThis builds the all-in-one image and starts it. Confirm it's actually ready before opening it in a browser:
docker compose psWait for STATUS to show (healthy) — that's Docker's own healthcheck,
which runs inside the container against genuine loopback. Don't use
curl http://localhost:5001/health from your host as a substitute: by
design that endpoint only answers loopback callers, and a request from the
host arrives via the Docker bridge instead, so you'll get a 403 even
though the instance is fine (HEALTH_ALLOWED_NETWORKS in
Configuration Reference controls this). If you
want a host-reachable check, curl http://localhost:5001/api/v1/version
returns 200 and isn't subject to that restriction.
Once docker compose ps shows healthy, open http://localhost:5001.
A fresh instance with AUTH_DISABLED=false opens straight to a setup form —
there's no separate login step yet, because there's no account to log in
with. Enter a username and a password (8+ characters, mixing case, a number,
and a symbol) and submit. Capstan creates the account and logs you straight
into the dashboard — you won't see the login page until you sign out or your
session expires.
The dashboard's tab bar is your map of everything Capstan manages on this host: Metrics (the landing view — CPU/memory/disk at a glance), Stacks, Containers, Dirs (directories Capstan scans for compose projects), Updates (available image updates), Images, Volumes, Networks, and Build Cache. With no stacks yet, most of these are empty — that's expected.
Click New Stack. The dialog opens with a starter compose template already filled in — edit it in place rather than starting from a blank file:
- Stack Name: give it a short, disposable name — this becomes both the
directory name under
STACKS_DIRand the Docker Compose project name. - Docker Compose: the default template runs
nginx:lateston host port 8080. Change the tag to something pinned (the linter warns on:latestfor exactly this reason) and adjust the port if 8080 is already taken on your host. - Leave Deploy after creation unchecked for now — you'll start it explicitly in the next step, which makes the create/start distinction clearer, and don't need it for a first stack.
- Click Create Stack. On a tall dialog, scroll down if the button isn't visible — the footer sits below the compose editor.
Capstan writes compose.yaml into the new stack directory and takes you to
the stack's Overview page, stopped.
Click Start. Capstan runs docker compose up -d against the stack's
directory and streams the output live — you'll see the network and container
get created, then stack running. The Containers table below updates to
show the container's State (Running), Status (Up N seconds), and
its Ports mapping.
Confirm it from outside Capstan too:
curl -I http://localhost:8088 # or whatever host port you setA 200 OK from nginx means the container Capstan just created is genuinely
serving traffic, not just reported as running.
Beyond Overview, the stack page has tabs for Compose (edit and redeploy
the compose file), Environment (the stack's .env), Logs (tailing
container output), Terminal (a shell inside the container), Metrics,
Updates, and Backups. These cover the day-to-day operations once a
stack is running; this tutorial stops at "created and running."
- Deploying somewhere other than your workstation: Production Deployment
- Protecting what you just built: Configuring Backups
- Every environment variable Capstan reads: Configuration Reference
- The full HTTP API surface behind the UI: API Reference
- How the pieces fit together: Architecture