lightmorphic/dockup repository overview

⁠Lightmorphic Dockup

A self-hosted Docker Compose stack manager for home labs, with a proper login. Inspired by Dockge - same idea, fresh code, different look, security first.

⁠What it does

• All your compose stacks on one dashboard, live status, one window
• Create stacks in a web editor with colour-highlighted YAML and live validation, or paste a docker run ... command and have it converted to compose
• Start / stop / restart / redeploy (recreate from the compose file, fixes a stuck container without pulling a new image) / update (pull newest images) / delete - one click
• A stack with no container shows a neutral gray status, with Archive (keep the folder, restorable later) and Delete (folder and every referenced image, nothing left behind) actions
• Checks every 30 minutes for a newer image per stack and flags it on the card - update one or "Update all", nothing pulls on its own
• Adopt what's already running, one at a time or all in one go: Dockup scans the system for compose projects and standalone containers it doesn't manage and pulls their setup into the stacks folder
• Live log streaming with errors highlighted in red
• Web terminal into any running container
• Prune unused images, containers, networks, volumes and build cache - separately or together, with volumes always a deliberate two-step
• Persistent activity log, optional email alerts on errors
• Daily backups with one-click (reversible) restore, plus a download-everything zip
• Per-stack backup including real data - bind mounts and named volumes, not just the compose file - with download and upload for moving a stack's backup to another machine or keeping a copy yourself
• Works with Docker or Podman - same UI, just point it at the other socket
• One click to open a stack's real web UI in a new tab - its Tailscale Serve address if set up, otherwise the host address you're already using to reach Dockup
• Its own update-status dot in the top bar - green up to date, amber a new version's published (click to download it in the background while Dockup keeps running as it is), then blue: click again to restart onto it. No separate check button; it keeps itself current on its own. Deliberately not a stack you can act on otherwise - stopping or deleting the tool managing everything else isn't a risk worth a click away
• Optional dockup-companion for host OS update checks and per-stack Tailscale Serve toggles - the one part of Dockup that needs root on the actual server rather than just Docker access, so it's a separate install step, fully automated with one click in Settings (or manually)

⁠Security

• Real server-side login with rate limiting and optional 2FA (TOTP)
• One secret in the environment (SECRET_KEY); everything else lives in the Settings screen, encrypted at rest
• Session cookies are HttpOnly + SameSite; CSRF-checked API; strict CSP; no CDNs, no tracking. The only thing not served by Dockup is the Lightmorphic app launcher in the top bar - see SECURITY.md to remove it

⁠Install

Dockup ships as a normal pre-built image (lightmorphic/dockup on Docker Hub) - no cloning, no building. All you need is the compose file:

mkdir -p /opt/dockup /opt/stacks && cd /opt/dockup
curl -fsSL -o compose.yaml https://dockup.lightmorphic.com/compose.yaml
echo "SECRET_KEY=$(python3 -c 'import secrets;print(secrets.token_urlsafe(48))')" > .env
docker compose up -d

Open http://<server-ip>:4000, create the admin account, done. Updating later is the update dot in Dockup's own top bar, or the usual:

docker compose pull && docker compose up -d

(Prefer building from source? Download https://dockup.lightmorphic.com/dockup-source.tar.gz⁠, unpack it into /opt/dockup instead and put build: . in a compose.override.yaml - everything else is identical.)

/opt/stacks is the recommended stacks folder - each stack is a plain folder with a compose file, so there's no lock-in: the folder works with plain docker compose (or any other manager) at any time.

⁠Optional: dockup-companion (Tailscale Serve + OS updates)

A second, separate step - only needed for host OS update checks and per-stack Tailscale Serve toggles. Everything else works without it. Easiest way: Settings → Host OS & Tailscale → "Install companion" (one click, once Dockup itself is running). Or manually:

The companion is inside the image, so taking it from there always gives you the version you are running:

mkdir -p /tmp/dockup-companion
cid=$(docker create lightmorphic/dockup:latest)
docker cp "$cid:/app/companion" /tmp/dockup-companion
docker rm "$cid"
cd /tmp/dockup-companion/companion && sudo sh install.sh

Then add the companion socket mount in a compose.override.yaml and restart Dockup. Full steps in runbook.md⁠.

⁠Podman instead of Docker

Enable the Podman socket, then swap the socket mount in compose.yaml (see the comment there) and flip the engine in Settings. The full steps are in runbook.md⁠.

⁠Day to day

Everything routine - restart, backups, restore, logs, pruning - is a button in the UI. The runbook⁠ covers the rest in plain language: install, restore, rollback, moving to Podman, and what to do when something's wrong.

⁠Licence

Dockup is free software under the GNU General Public License v3.0 - see LICENSE⁠. You may use, study, change and share it; if you distribute a changed version, it has to carry the same freedoms.

Bundled third-party bits: xterm.js⁠ (MIT) for the terminal, Manrope⁠ (SIL OFL) for the type. Python dependencies are in requirements.txt - all permissively licensed (BSD/MIT/Apache).

Comments are stripped from the published code to keep it lean.