Stacks

Deploy, stop, start and read the logs of a stack, or make a new one with the wizard.

Everyday commands

seawall stack ls                 # every stack, its state and pending updates
seawall stack diff nextcloud         # disk copy against what runs
seawall stack deploy nextcloud --yes
seawall stack stop nextcloud --yes
seawall stack start nextcloud --yes
seawall stack logs nextcloud -n 200 -f
CommandDoes
stack deployDeploys the disk copy. Sends the stack's env back with it. Backs up what runs to the backups folder (paths.backups) first. --pull pulls the images first. --set-env NAME takes a value from your shell. A stopped stack stays stopped unless --start. A new lint error, a database major without a tested dump and a root grant not yet accepted stop the deploy: --allow-lint-errors, --data-backed-up and --accept-grants or --confirm pass them.
stack rollbackDeploys the newest backup that differs from what runs, by its compose or by the build it recorded. It pins each service whose build the backup recorded to that build's digest, where it has a registry digest, and says the stack is back only once those services' containers run that build. It writes the disk copy too.
stack removeRemoves a stack through its manager. It backs up the compose file and dumps and restore-tests each database first. Then its own networks, expected ports and proxy routes go. Its volumes go only with --volumes, each copied to a tar file first. --keep-routes leaves its proxy routes. The stacks of Portainer, the proxy, monitoring, logging and CrowdSec are refused.
stack reconcileEnds drift. --take disk deploys the disk copy. --take deployed writes what runs to disk.
stack stopSilences the stack's container alerts for 1h (--silence), stops each container so it can save, then removes the containers. Volumes and bind mounts stay.
stack startStarts a stopped stack and lifts the silence its stop set.
stack logsPrints log lines with escape codes removed. Errors show red and warnings yellow. Lines over 4000 characters are cut. -f follows them.
stack findLists every stack on the host and marks those outside the stacks folder. stack move brings one in.
stack migrateMoves a stack between Portainer and Compose. It moves it back if it doesn't come up, and a stopped stack stays stopped. A relative bind such as ./data is pointed at where Portainer really kept the data. A Portainer stack whose disk copy builds (build:) moves to Compose with that copy. The plan shows its changes from Portainer's copy.
stack secretsLists env var names set against names used. It never prints a value.
stack editOpens the disk copy in your editor, then shows the deploy plan.
stack envLists the stack's env names. set NAME asks for the value with typing hidden. rm NAME removes one. A stopped stack takes a change only with --start, which starts it. It never prints a value. In the TUI's env editor, setting a value written in the compose rewrites its line to take the value from the stack's env.
containerls, inspect, restart, stop, start and shell act on one container. inspect masks env values. shell runs as the container's own user. A root shell asks you to type the container's name.
volumes, networks, images prunevolumes ls|rm and networks ls|rm show what each is used by. A removal asks you to type its name and a prune asks for images. Images that stopped stacks use are kept.

A deploy, update, rollback, stop or game down stops each container it replaces before its manager does. A container still working at its grace period gets more time, up to 5 minutes. One that has gone quiet past its grace period is killed. The output says so and names any permission error it logged.

After a deploy seawall waits for each container to settle. It runs the container's own health check every 2 seconds. A container without one has to stay up for 10 seconds. A stack that doesn't settle is named with the reason. On a terminal you are offered a rollback. --rollback-on-failure rolls back without asking.

A container that restarts three times while it settles is crash-looping. Off a terminal, or with --rollback-on-failure, the deploy is rolled back at once and the reason is named. On a terminal you are asked, as for any deploy that doesn't settle.

Two minutes after a change that redeploys a stack, the facts timer reads it again and compares it with before. It checks each container's state, health and restarts, the alerts that name the stack and new errors in its logs. It requests each domain routed to the stack through the proxy on this host. Where Prometheus runs it reads the stack's probes, CPU throttling and its Uptime Kuma monitors when Prometheus scrapes Kuma. A stack that got worse raises SeawallDeployWorse with the cause and the rollback. --wait waits out that comparison in the command instead. Log lines are shown with the stack's env values masked.

seawall stack update hc30 with its progress bar at the deploy step and the finished steps above it
An update in progress. Finished steps stay above the bar with their times.

Who runs a stack

The BY column of stack ls says who runs each stack. seawall reads it from the host and needs no setting for it.

BYMeans
portainerPortainer has the stack.
composeIts containers run with Compose from a folder in the stacks folder.
splitPortainer has the stack and its containers also run from a folder. Deploy, update, stop and migrate refuse it. Remove one of the two first.

A Compose project counts only when its folder and compose file belong to the owner of the stacks folder. Links are followed first. Neither may be writable by other users. Group write is allowed only for the owner's private group. stack ls names any other project on a line of its own, as a project seawall doesn't manage. Name one under [manager.stacks] to take it on.

A container counts only when Compose made it. Compose labels baked into an image never put a container in a stack or point seawall at a folder.

[manager.stacks] overrides what the host shows. manager.default decides only where a new stack goes.

New stacks

seawall new                         # the wizard
seawall stack new games/valheim --set-env SERVER_PASS --yes

seawall new asks what you are making (an app behind the proxy, an internal service or a game server), then the image. Words search Docker Hub. A name lists its tags with the newest stable release first. A moving tag such as latest is pinned by digest. It reads the image and its README for ports, data folders and settings. Each default shows where it came from.

The wizard's How should it run question with the suggested choice selected
One wizard question. The suggested choice is first and selected.
QuestionNotes
How should it run?An image that switches to PUID/PGID runs as your user. An image with its own user runs as that user. A game server otherwise starts as root and switches in its own start script. Root throughout is always last.
Public game portsFrom the image or its README. An image that exposes none gets its *_PORT settings, as UDP except RCON, HTTP, WEB and API ports.
Data foldersRequired for a game server. Type none only if it keeps nothing.
Lock the image's files?Apps and internal services only. Writes read_only: true with a tmpfs /tmp.
SettingsA form of the image's settings and those its README names. Only changed values are written. Changing a *_PORT setting moves its published port.
SecretsEnv var names whose values are set in the stack's env, never in the file. none declines the suggested ones.

In the settings form ↑ ↓ move between settings, typing changes the value, ctrl+u clears it and esc goes back a question. On the CLI each setting is a prompt. enter keeps the value, "" empties it and < steps back one.

stack new lints the folder, creates the stack, opens its public ports in the allowlist and maps it in the config repo. A non-root service gets each new volume made and handed to its user first.

Portainer can't build images. seawall refuses a Portainer stack with build: before anything changes. Run it with Compose instead. Add myapp = "compose" under [manager.stacks] first.

One container

seawall container ls nextcloud
seawall container inspect nextcloud-app-1
seawall container restart nextcloud-app-1 --yes
seawall container shell nextcloud-app-1 --yes
seawall container adopt vaultwarden --yes

container acts on one container while the rest of its stack keeps running. inspect shows every env value as <set>, and passwords and tokens in its command or labels the same way. stop silences that container's alerts first and start lifts the silence. shell runs as the container's own user. A container that runs as root, even under another name for uid 0, needs --root and its name typed.

container adopt brings a container started with docker run under a stack written from how it runs. Its env values go to the stack's env, never into the compose file. The old container is renamed <name>-before-seawall and stopped. If the stack doesn't come up healthy, it goes and the old container starts again. A container a compose project already owns is refused, and so is one that runs with something compose can't say, unless --accept-missing. container rm takes the name typed.

Behind the proxy

seawall proxy route add blog blog.example.org --yes
seawall stack expose wiki web wiki.example.org --yes
seawall npm fix blog.example.org --yes

proxy route add makes a stack's proxy host with a certificate that covers the domain or a new one from Let's Encrypt. It works with Nginx Proxy Manager only, as seawall's own NPM user (proxy login). Traefik and Caddy route from the stack's labels or the Caddyfile. Until the certificate is there the host is disabled, so nothing is served without TLS. stack expose takes a service that publishes a host port, joins it to the proxy network, stops publishing and routes it. It refuses a service with more than one published port until you name the web port, and one on another service's network. A stack that doesn't come up is put back with its compose file.

Neither puts something that is root on the host behind the proxy as it is. That covers Portainer, a container that mounts the Docker socket or can reach a socket proxy that lets writes through, and one that runs privileged, in the host's PID namespace, with broad capabilities or with a bind mount of a system folder. Such a target needs --allow with the addresses you manage it from, and the access list is checked in what nginx serves. Portainer's route is made only by init's infra-routes step.

npm fix turns Block Common Exploits off for an MCP host, turns websockets and the buffering block on, and forces HTTPS where the host has a certificate. It leaves a disabled host as it is.

Folders no manager runs

seawall stray ls
seawall stray ignore ~/docker/old-app
seawall stray adopt ~/docker/old-app --start --yes
seawall stray rm ~/docker/old-app --yes

A stray is a folder with a compose file that neither Portainer nor Compose runs as a stack. stray ls lists each one with its state, such as a git checkout with changes. ignore leaves it alone from then on (paths.ignore). adopt makes it a stack, moving it into the stacks folder first when it lives elsewhere. On a Portainer host, a folder Portainer can't run from its one copy (it builds, reads another file, or binds a relative path) comes in on Compose. On Compose the folder's .env is kept as the stack's settings, closed to 0600. Its dry run names any lint errors and --allow-lint-errors starts it with them. rm keeps a tar.gz of the folder under the backups folder, reads it back against the folder's files and only then moves the folder into ~/.local/share/seawall/stray-trash/, which seawall doesn't empty.

rm and adopt refuse a folder that a Compose project binds or a folder above it. seawall reads each project's compose and override files, its .env and what they include and extends itself, without Docker. It reads the projects in the stacks folder, in the folders seawall.toml and the stack records name, and in the folders its walk finds (your home four levels down, /opt and /srv three). A project it can't read refuses every other folder, and stray ls lists the rows as unread with the reason.

The walk reads only folders you own or can search. A folder another user owns is skipped, and a folder you own that it can't search or list is unread. It doesn't see these:

  • A folder in paths.ignore. Ignoring a folder it can't read is the way past it.
  • Hidden folders, folders below a git checkout outside the stacks folder, and folders named node_modules, target, venv, __pycache__, proc, sys, snap, lost+found or backups.
  • A project known only by a volume or network label, whose files are in no folder seawall walks or records.
  • A project name or -p that a shell gave to up.

A rootless runtime

seawall stack runtime ghost --to podman-rootless
seawall stack runtime ghost --to podman-rootless --yes
seawall stack runtime ghost --clean --yes
seawall stack runtime ghost --back --yes

A stack can move off root's Docker onto a rootless runtime, Podman or rootless Docker, run by an account of its own. Set runtime.owner to that account and run init, whose runtime-access step gives the runtime a socket the access group reaches. A container that breaks out of its runtime then lands as that account.

stack runtime <stack> --to plans the move and changes nothing. It refuses a stack that doesn't run as its own user, files owned by ids outside the account's subordinate range, databases, ports published past loopback, builds, setuid or setgid files, extended attributes, a proxy-trust setting holding the proxy network's addresses and too little room. The plan lists each volume and bind folder with its size, the proxy hosts that move and compose.rootless.yml, the file Compose reads after the stack's own on the new runtime.

With --yes seawall logs in to NPM and pulls the images first, then silences the stack's container alerts (15 minutes, --silence) and stops it. Each volume and bind folder is copied by tar into a new volume on the new runtime and checked by a digest of both sides. The stack starts there through Compose. A routed stack's proxy reaches it on a port of the proxy network's gateway. A ufw rule lets in only the proxy's bridge, so the move is refused while ufw is off. NPM's hosts are pointed at that port and each domain is checked through NPM. Compose then runs the stack and Portainer's copy is removed. Every step is written to a journal first. A failure rolls back and starts the stack on root's runtime again. Run the command again without --to to finish or roll back a move that stopped part way.

A bind folder becomes a named volume, so a stack with bind folders moves one way only. You type its name to move it, or pass --confirm NAME. The old copy stays on root's runtime until --clean removes it. A volume or a folder's files go only while each still has its digest from the move and nothing on root's runtime mounts it. A folder is emptied only under the stacks folder with no link on its way.

--back brings a moved stack back to root's runtime with what it wrote since. Only the stack's own volumes come back. Root's copy from before the move is kept first as a tar in ~/backups/<stack>/ and proved whole before it's replaced. Setuid and setgid files are refused, and NPM is pointed at the stack's container again. --clean after a move back removes the volumes the rootless runtime still holds.

Stop, start, deploy, logs and the health checks reach a moved stack on its runtime. Its logs stay there, out of Loki and the alert-context dashboard, so its container alerts name seawall stack logs as their check. Pulls there are anonymous, since your registry logins never reach a daemon another account runs. run-as and the PID 1 fix refuse a moved stack. When a session can't see the rootless runtime, its containers are left out of every list and that's said once.