Docker deployment

The Envoy container image packages the binary, UI assets, bundled tasks and jobs, technical references, seed data, connector catalog assets, and Litestream.

The same image can start either runtime role:

# Control plane
command: ["server", "--config", "/app/state/envoy-server.yaml"]
 
# Executor
command:
  - executor
  - --control-plane
  - http://control-plane:3000
  - --port
  - "9090"

Use Remote Docker deployment for the production host workflow. This page explains the image contract shared by Compose deployments.

First-boot config generation

The entrypoint generates the file at ENVOY_CONFIG_PATH when:

• the file does not already exist; and
• ENVOY_ENCRYPTION_KEY is set.

It writes server, state, runs, retention, branding, tasks, jobs, executor, database, secrets, auth, AI, and external log sections according to available environment variables.

Generation is intentionally one-time because the file is persisted. To change an established deployment, update the YAML or use deployment automation that explicitly patches it.

Mounts

Use three separate durable mounts:

volumes:
  - /opt/envoy/state:/app/state
  - /opt/envoy/data:/app/data
  - /opt/envoy/dbs:/app/dbs

• /app/state belongs to the server and should not be used as general connector storage.
• /app/data is for file connectors.
• /app/dbs is for workload SQLite databases.

Mount the data and connector database paths into both control plane and executor when the UI tests/uploads files and the executor later processes them.

Network ports

The control plane listens on port 3000 in the standard image. The remote compose file publishes it only on host loopback. The executor listens on 9090 inside the deployment network and is not normally published.

Terminate TLS at the platform ingress or host reverse proxy and set secure cookies.

Read-only executor

The hardened executor uses a read-only image root with writable tmpfs for runtime scratch. Relative paths resolve under /app, which is not writable.

Use:

path: /app/dbs/mapping.db
directory: /app/data/imports

Do not use:

path: ./mapping.db
directory: ./data

Seed import

The image includes task, job, and AI-reference seeds. The control plane can import them at first boot. Set ENVOY_SKIP_SEED_IMPORT=true only when your deployment intentionally manages all definitions elsewhere.

Imported database records are independent from the files after import; understand the deployment's update process before expecting changed bundled YAML to overwrite edited records.

Litestream

When the state backend is SQLite and backup environment variables are complete, the entrypoint:

1. generates a Litestream config;
2. restores the state database if the local file is absent and a replica exists;
3. runs Envoy under litestream replicate.

For non-SQLite state, Envoy starts directly and Litestream state replication is skipped.

Container logs and run logs

Entrypoint and service diagnostics appear in container stderr. Per-run task logs are captured by the configured run log store. They are different streams and should both be available to operators.

Useful Docker inspection commands:

docker compose ps
docker compose logs --since=30m control-plane
docker compose logs --since=30m executor

Avoid pasting logs that contain connector payloads into public tickets. Redact credentials, tokens, customer records, and connection strings.