deploy/portainer/
Portainer stack templates for Mosaic Stack deployments.
Files
| File | Purpose |
|---|---|
federated-test.stack.yml |
Docker Swarm stack for federation end-to-end test instances (mos-test-1.woltje.com, mos-test-2.woltje.com) |
federated-test.stack.yml
A self-contained Swarm stack that boots a federated-tier Mosaic gateway with co-located Postgres 17 (pgvector) and Valkey 8. This is a test template — production deployments will use a separate template with stricter resource limits and Docker secrets.
Deploy via Portainer UI
- Log into Portainer.
- Navigate to Stacks → Add stack.
- Set a stack name matching
STACK_NAMEbelow (e.g.mos-test-1). - Choose Web editor and paste the contents of
federated-test.stack.yml. - Scroll to Environment variables and add each variable listed below.
- Click Deploy the stack.
Required environment variables
| Variable | Example | Notes |
|---|---|---|
STACK_NAME |
mos-test-1 |
Unique per stack — used in Traefik router/service names. |
HOST_FQDN |
mos-test-1.woltje.com |
Fully-qualified hostname served by this stack. |
POSTGRES_PASSWORD |
(generate randomly) | Database password. Do not reuse between stacks. |
BETTER_AUTH_SECRET |
(generate: openssl rand -base64 32) |
BetterAuth session signing key. |
BETTER_AUTH_URL |
https://mos-test-1.woltje.com |
Public base URL of the gateway. |
Optional variables (uncomment in the YAML or set in Portainer):
| Variable | Notes |
|---|---|
ANTHROPIC_API_KEY |
Enable Claude models. |
OPENAI_API_KEY |
Enable OpenAI models. |
OTEL_EXPORTER_OTLP_ENDPOINT |
Forward traces to a collector (e.g. http://jaeger:4318). |
Required external resources
Before deploying, ensure the following exist on the Swarm:
traefik-publicoverlay network — shared network Traefik uses to route traffic to stacks.docker network create --driver overlay --attachable traefik-publicletsencryptcert resolver — configured in the Traefik Swarm stack. The stack template referencestls.certresolver=letsencrypt; the name must match your Traefik config.- DNS A record —
${HOST_FQDN}must resolve to the Swarm ingress IP (or a Cloudflare-proxied address pointing there).
Deployed instances
| Stack name | HOST_FQDN | Purpose |
|---|---|---|
mos-test-1 |
mos-test-1.woltje.com |
DEPLOY-03 — first federation peer |
mos-test-2 |
mos-test-2.woltje.com |
DEPLOY-04 — second federation peer |
Image
The gateway image is pinned by digest to fed-v0.1.0-m1 (verified in DEPLOY-01). Update the digest in the YAML when promoting a new build — never use :latest or a mutable tag in Swarm.
Notes
- This template boots a vanilla M1-baseline gateway in federated tier. Federation grants (Step-CA, mTLS) are M2+ scope and not included here.
- Each stack gets its own Postgres volume (
postgres-data) and Valkey volume (valkey-data) scoped to the stack name by Swarm. depends_onis honoured by Compose but ignored by Swarm — healthchecks on Postgres and Valkey ensure the gateway retries until they are ready.