stackd

A tiny boot orchestrator + watchdog for your Docker stacks.

stackd decides which of your stacks come up at boot and keeps them alive — and it does it by driving the stacks program, not by reimplementing any of its logic. Think of it as the conductor: stacks knows how to bring a stack up, repair it, or recreate it; stackd just decides what to start, in what order, and with which strategy, then hands off.

It replaces Docker's own "restart whatever was running" autostart with something you actually control: a single config file listing exactly what you want running 24/7 — by whole stack or by individual service.

Why

Docker's default boot behavior just restarts whatever had restart: always — all-or-nothing, no ordering, no health escalation. If you run dozens of stacks but only want a handful up 24/7 (reverse proxy, DNS, auth, tunnel…) with the rest asleep until something wakes them, Docker can't express that. stackd can.

How it works

1. On install, stackd sets every container to restart=no — Docker stops auto-starting things. stackd is now in charge.
2. At boot, stackd boot starts only the services in your config, each via stacks up <stack> [service] <strategy>, escalating only if a service comes up unhealthy.
3. stackd watch keeps that set alive, healing anything that falls over.
4. Optionally it pre-pulls every other stack's images and leaves them stopped, so on-demand services start instantly when something wakes them.

Install

go build -o stackd .
sudo cp stackd /usr/local/bin/
stackd config init                 # writes ~/.config/stackd/config.yaml
$EDITOR ~/.config/stackd/config.yaml
sudo stackd install --dry-run      # preview exactly what it will change
sudo stackd install                # write units + set restart=no
sudo systemctl enable --now stackd-boot.service stackd-watch.service

Requires the stacks program it drives, plus Docker and systemd.

Config — ~/.config/stackd/config.yaml

start_strategy: repair        # repair | fix | recreate  — how each service is started
escalate: true                # if it comes up unhealthy, try the steps below (only if needed)
escalation: [recreate, fix]
download_missing: true        # pull every OTHER stack's images, leave them STOPPED
watch_interval: 30            # watchdog check interval (seconds)
stacks_cmd: /usr/local/bin/stacks

boot_services:                # THE 24/7 LIST
  - net_1                     # a whole stack…
  - net_2/traefik             # …or a single service inside a stack
  - net_3/authentik_server

• start_strategy — pick repair, fix, or recreate for the first (gentle) start pass.
• boot_services — stack starts the whole stack; stack/service starts just that one service. Mix freely.
• download_missing — make sure every stack's images are on disk without running them.

Commands

command	what it does
stackd boot	start the configured 24/7 set (one-shot; used by the boot unit)
stackd watch	watchdog loop that keeps the 24/7 set alive
stackd status	show the config + which 24/7 services are up right now
stackd install / uninstall	manage the systemd units + Docker autostart
stackd config init	write a default, fully-commented config

Every command accepts --dry-run.

Design notes

• Thin on purpose. No repair/recreate/fix logic lives here — it all stays in stacks. Improve stacks, and stackd benefits for free.
• Per-service granularity using the Compose project + service labels.
• Config resolution mirrors stacks ($STACKD_CONFIG_DIR → invoking user's home under sudo → $XDG_CONFIG_HOME → ~/.config) so the root-run boot unit still finds your config.

License

MIT