Stack Management

dockmesh manages stacks — groups of containers defined by a Docker Compose file. Each stack lives on disk as a directory containing compose.yaml and an optional .env file. The filesystem is always the source of truth; the database only stores metadata and runtime state.

Creating a stack

Stacks → New stack opens a modal where you name the stack and choose how to supply the compose source: paste/edit YAML in the Compose editor, or pull it From git repository.

On a multi-host install the modal also shows a Deploy on host dropdown — pre-filled with whatever the sidebar host switcher had selected. On single-host installs the dropdown is hidden to keep the form lean (everything lands on local anyway).

The modal footer has two actions:

Create — writes compose.yaml to disk and stops there. The stack exists but no containers run yet.
Create & deploy — writes the file and immediately deploys it on the chosen host. Requires stacks.deploy (button is disabled otherwise).

compose.yaml is written to disk host-neutrally at <DOCKMESH_STACKS_ROOT>/<name>/compose.yaml — one directory per stack, no host subdirectory. The host binding lives in the stack_deployments table and is set on the first deploy; the detail page reads from there.

Import from `docker run`

Click Import from docker run at the top of the create modal and paste a docker run … command. dockmesh’s converter (POST /api/v1/convert/run-to-compose) extracts image, ports, volumes, env vars, restart policy, labels, and most common flags into a compose snippet.

Multi-line commands with backslash line continuations (the format most upstream READMEs use) are accepted as-is — the parser collapses \<newline> to a single space before tokenising, so the Vaultwarden / Authentik / Nextcloud copy-paste examples Just Work. Both LF and CRLF line endings are normalised, so pasting from a Windows clipboard is fine too.

Unsupported flags don’t fail the conversion — they get reported in the warnings list above the generated YAML so you can decide whether the missing flag matters (e.g. resource limits or healthcheck overrides currently land in warnings rather than the snippet).

Detail page actions

The stack detail header exposes three actions:

Deploy — pulls images, creates/updates containers, applies compose changes (two-phase: all images pre-pulled before any container is torn down)
Stop — graceful stop with the configured timeout
Migrate — only visible when more than one host is available; moves the stack to another host (volumes transferred over the mTLS tunnel)

Deploy progress streams live into the UI so you see each phase (pull, create, start, healthcheck). Restart, pull-without-redeploy, and remove are not separate buttons — re-deploy after editing the compose handles “update”, Settings → Configuration for the stack covers cleanup of orphaned resources, and tear-down with the stack files preserved is reached via the destructive section at the bottom of the detail page.

Editing a stack

The compose.yaml editor is a plain monospaced textarea — no Monaco, no autocomplete. Validation happens server-side: invalid YAML or unresolvable images surface in the deploy log rather than the editor. Pair the editor with your own IDE if you want full Compose schema awareness, then paste the result.

Git integration

Point a stack at a Git repo (HTTPS or SSH) and dockmesh polls for updates on the configured interval. When auto_deploy is on, a new commit triggers a redeploy. A webhook secret can be configured for HMAC-verified push triggers from your CI — no custom code required.

Stack templates

Save any stack as a template so you can spin up copies later from Templates in the sidebar. Templates currently clone the original compose 1:1 — there is no built-in variable substitution layer; differentiate copies by editing the resulting stack after creation, or rely on the Environment page for shared values.