Deploy with Docker Compose

Run AgentTeam Email on one host with the root Docker Compose files.

Docker Compose is the supported single-host deployment path. The root compose.yaml runs the web server, mail control service, MongoDB, Redis, WildDuck, Haraka, Rspamd, and ZoneMTA on the external agentteam-email-network Compose network. Only the web server port is published.

Complete the Self-Host Setup Guide before starting the stack.

Create the environment file

Copy the Compose example into a local .env file:

cp docs/examples/compose/.env.example .env

Populate every uncommented value. Commented entries in the example are defaulted or optional overrides; leave them unset unless you are intentionally changing the default Compose topology or enabling an optional integration.

Use the Environment Variables reference for the full variable contract. The required groups for the default compose.yaml stack are:

• public hostname and web app secrets
• Cloudflare OAuth client ID
• service-level Cloudflare Worker values
• admin R2 archive bucket values
• AT_EMAIL_ADMIN_CONTROL_TO_WEB_API_TOKEN
• WildDuck admin and access-control secrets
• mail runtime secrets

compose.yaml defaults MongoDB, Redis, WildDuck, Haraka, ZoneMTA, and the internal control URLs to services on the Compose network. The bundled MongoDB runs as a single-node replica set named rs0, matching the Helm chart runtime and supporting MongoDB transactions and oplog-based logical backups.

Start the stack

Create the external Compose network, or let your deployment platform provide it:

docker network create agentteam-email-network

Run Compose from the repository root:

docker compose up -d
docker compose ps

Wait for atemail-web-server and atemail-mail-control-service to report healthy before signing in.

Published service

Compose publishes the web app on AT_EMAIL_ADMIN_FRONTEND_PORT, which defaults to 23100:

AT_EMAIL_ADMIN_FRONTEND_PORT=23100

Route your public hostname to that web server listener. Do not publish internal service ports.

Container images

First-party images are published in GHCR:

ghcr.io/agentteamhq/agentteam-email/atemail-web-server
ghcr.io/agentteamhq/agentteam-email/atemail-mail-control-service

Pin the image tag with:

AT_EMAIL_ADMIN_VERSION=0.5.0

Control pull behavior with:

AT_EMAIL_ADMIN_PULL_POLICY=always

To build the first-party images from the checked-out repository instead of pulling GHCR images, overlay compose.build.yaml:

docker compose -f compose.yaml -f compose.build.yaml up -d --build

Persistent volumes

The default Compose stack creates named volumes for runtime data:

Volume	Contents
mongodb-data	MongoDB data directory
redis-data	Redis persistence files
rspamd-data	Rspamd learning and statistical data
haraka-queue	Haraka inbound mail queue

Back up these volumes before upgrades. Data remains across docker compose down unless you pass --volumes.

Never commit .env. It contains secrets, credentials, and API tokens.