Add an application stack

Servestead keeps the Compose file consumer-owned and stores public routing as separate metadata. Every service can deploy. Only routes you explicitly define become public through Pangolin.

Before you begin

The profile needs a configuration repository and a completed Platform stage. Prepare a working Compose model and decide which service ports, if any, should be public.

1. Open the stack manager

Run servestead setup, select the profile, then press s. Press a to open the Compose file picker or / to type a path.

The Compose file must parse and contain at least one named service.

2. Choose public services

Servestead lists every detected service as private by default.

• Press space to make the selected service public or private.
• Press enter to configure its route.
• Press a to add another route for the same service.
• Press n when the public service choices are complete.

Each public route controls the Compose service, container port, subdomain, stable ID, display name, protocol, SSO, and health check. Press ctrl+x in the route editor to show the advanced fields.

3. Choose runtime secrets

The next screen offers no runtime secrets, a detected adjacent .env, or another file. Servestead records values in the encrypted stack secret file and shows only variable names after save.

Do not commit a populated .env. Commit an .env.example when operators need the required names.

4. Save local files

The final review shows the Compose path, service counts, routes, and secret key count. Saving writes local repository files. It does not deploy or commit.

File	Purpose
stacks/<name>/compose.yaml	Your reviewed Compose model.
stacks/<name>/servestead.yaml	Public-resource contract and route metadata.
stacks/<name>/servestead.secrets.yaml	Age-encrypted runtime values when configured.

Servestead does not inject labels into the consumer-owned Compose file.

5. Review Git and deploy

Back in the stack manager, press v to inspect the diff, g to stage managed stack changes, c to commit, and p when the branch needs a push. Select the committed stack and press r to deploy it. Press y when you intend to reconcile every committed stack.

The run validates the merged Compose model before replacing containers and verifies the expected Pangolin resources afterward.

Edit or remove a stack

Select an existing stack and press e or enter to edit it. Press ctrl+s to save an edit.

Press d to review local deletion. The prompt shows the stack path and explains the later remote effect. Enter delete <stack-name> exactly as shown. Commit the deletion, then press y only when you want reconciliation to remove its remote resources.

Runtime data paths

Use /data/<stack>/... for application bind mounts. Servestead creates the stack data directory with owner 1000:1000 on first deployment. Use a named volume or prepare the directory yourself when an image runs as another UID or GID.

Do not bind writable application data from /opt/servestead/repository. That checkout is deployment input.

Direct command

For a scripted import:

./bin/servestead stack add \
  --profile <profile-id> \
  --compose /path/to/docker-compose.yml \
  --publish web:3000:app \
  --env-file /path/to/.env

--publish is repeatable and uses service:port:subdomain[:id]. Omitting it creates a private stack.