b242509675
docker-compose.yml gains a postgres service (EXECUTER-DB-00001, official
image pinned by major and digest like NATS, INTERNAL network only, no host
port, pg_isready health check, shm_size, runs as PUID:PGID, data in
${STACK_BINDMOUNTROOT}/${STACK_NAME}/Postgres/Data). It is in the "postgres"
Compose profile; COMPOSE_PROFILES in .env turns it on, and the backend waits
for it healthy (depends_on required: false, so SQLite and external databases
start without it). The backend defaults to DATABASE_PROVIDER=postgres with
DATABASE_CONNECTION_STRING and DATABASE_PASSWORD from .env.
docker-compose.postgres-port.yml publishes a host port, opt-in through
POSTGRES_BIND.
deploy.sh decides the database: what .env names when the operator set it;
else SQLite when API/Data/app.db exists (written to .env, with a note on how
to move); else the bundled Postgres, its password generated into .env (and
exported), never regenerated over an existing database. COMPOSE_PROFILES
follows. The decisions are functions that scripts/tests/Test-DeployDatabase.sh
runs on fixtures without Docker. Compose 2.20.2+ is checked; a new .env is
mode 600. New-LocalSecrets.ps1 generates the password for a new .env and
keeps an existing .env's database settings on -Force.
README: deploy, secrets, Compose, database providers, Postgres backups and
pg_restore, and Moving from SQLite to Postgres (migrate-database).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Infrastructure as Code
Deployment manifests for ExecuteR, in increasing order of scale:
| Target | Folder | Use it for |
|---|---|---|
| Docker Compose | compose/ |
A single host. The default; scripts/deploy.sh drives it. |
| Docker Swarm | swarm/ |
A few nodes, replicas behind one VIP, minimal orchestration. |
| Kubernetes | k8s/ |
Many nodes, HPA, rolling updates, cloud/multi-cloud. |
All three run the same images (executer-backend, executer-webui) and
the same NATS. They differ only in how many replicas run and how state is
shared. See the Scaling and HA wiki page for
the full picture and diagram.
What is stateless vs. stateful
Scaling past one backend/webui instance is safe because the realtime fan-out is NATS's job, not the backend's — agents and browsers hold their WebSocket to NATS through the edge, so replicas don't multiply that load.
Stateless (scale freely):
- WebUI — pure SSR/static; any number of replicas.
- Backend REST — cookie auth, no server-side session store. Round-robin; no sticky sessions needed.
- Backend ingest workers — subscribe with a NATS queue group, so each presence/inventory/job message is processed by exactly one replica.
Stateful / single-owner (needs shared infrastructure):
- Database — must be Postgres or SQL Server (not the SQLite default) so all backends share one store.
- Data Protection key ring — all backends must share it (cookies, CSRF,
encrypted secret blobs). Mount
DATAPROTECTION_PATHon shared storage (CephFS/MicroCeph, NFS) — every manifest here does. - Schedule worker — must run in exactly one place or schedules fire N
times. Run web/API replicas with
SCHEDULE_WORKER=0and one dedicated worker replica withSCHEDULE_WORKER=1(swarm/k8s do this). - NATS + JetStream — a 3-node cluster (JetStream R3) for HA; a supercluster with gateways spans regions/clouds.
Cross-cutting prerequisites for multi-instance
- Shared storage for the key ring (and NATS JetStream if not clustered):
MicroCeph/CephFS or NFS, exposed as a Swarm volume driver or a k8s
ReadWriteManyStorageClass. - A private overlay between nodes/regions — WireGuard via Tailscale or NetBird — so NATS cluster/gateway routes and the DB travel encrypted across sites without public exposure.
- Service discovery — Swarm and k8s both provide DNS
(
tasks.<service>/<service>.<ns>.svc); NATS cluster routes and DB hosts use those names. - One edge / single DNS name terminating TLS and load-balancing the replicas (see Networking and TLS).