On a server
Run the engine and the gateway on a Linux server with Docker Compose, behind Caddy or your own reverse proxy.
On a server the engine runs headless: your mail syncs and scheduled sends go out while every device is off. You use it through the web client, served by the gateway, and optionally through MCP for agents.
deploy/server/ in the repository is a Docker Compose setup. It runs one service per component, all from the airpost-server image:
| Service | Profile | Default | What it runs |
|---|---|---|---|
engine | always on | on | airpost-engine --mode serve --detached: syncs the accounts, keeps their credentials |
gateway | web | on | airpost-gateway serve with the web client |
caddy | proxy | on | TLS for AIRPOST_DOMAIN; leave it out behind your own proxy |
mcp | mcp | off | airpost-mcp http at https://<domain>/mcp, for agents with a bearer token |
backend | backend | off | Not available yet; leave it off |
Each runs as a separate process in its own container, read-only, with all capabilities dropped. Docker restarts one that stops. The image has no shell; it includes the airpost CLI for admin inside the engine’s container.
The image ghcr.io/airpost/airpost-server isn’t published yet. Until it is, build it from a checkout (step 3).
The files in deploy/server/
| File | What it does |
|---|---|
compose.yaml | The services, volumes and network. Start here. |
.env.example | Every variable you set, with comments. Copy it to .env, which .gitignore keeps out of git. |
Caddyfile | Caddy’s routes for AIRPOST_DOMAIN, used with the proxy profile. |
compose.own-proxy.yaml | Override: publishes gateway, MCP and backend on 127.0.0.1 for a host proxy or a local trial. |
compose.build.yaml | Override: builds airpost-server:dev from the checkout instead of pulling. |
Dockerfile | The image: web client, all five binaries, distroless runtime. |
Dockerfile.dockerignore | Keeps the build context to the sources the Dockerfile copies. |
mcp.json | The MCP policy, mounted read-only into the mcp container. |
compose.yaml
The project is named airpost-server, so volumes are airpost-server_profile and so on. Every Airpost service inherits one anchor, x-airpost:
x-airpost: &airpost
image: ${AIRPOST_IMAGE:-ghcr.io/airpost/airpost-server}:${AIRPOST_VERSION:?set AIRPOST_VERSION in .env}
restart: unless-stopped
init: true
read_only: true
tmpfs:
- /tmp
cap_drop: [ALL]
security_opt: ["no-new-privileges:true"]
networks: [airpost]
AIRPOST_VERSION has no default: Compose refuses to start without it. The root filesystem is read-only, with /tmp as tmpfs; the only writable paths are the mounted volumes.
enginerunsairpost-engine --mode serve --detached, mountsprofileat/profileandengine-keyat/keys, and passes the three OAuth client variables. Its health check isairpost statusevery 30 seconds with a 60-second start period.stop_grace_period: 30sgives it time to finish writes ondocker compose stop.gateway(profileweb) runsairpost-gateway serveand waits for the engine to be healthy. It setsAIRPOST_GATEWAY_PUBLIC_URLfromAIRPOST_PUBLIC_URL, falling back tohttps://$AIRPOST_DOMAIN, andAIRPOST_TRUSTED_PROXIESto the compose subnet. The bind address (0.0.0.0:5180) and web root come from the image.mcp(profilemcp) runsairpost-mcp http --bind 0.0.0.0, reads its policy from/etc/airpost/mcp.json(AIRPOST_MCP_POLICY), and accepts onlyAIRPOST_DOMAINasHost(AIRPOST_MCP_ALLOWED_HOSTS).backend(profilebackend) runsairpost-backend servewith its ownbackend-dataandbackend-backupsvolumes. It isn’t available yet; leave it off.caddy(profileproxy) is the stockcaddy:2image. It publishesAIRPOST_HTTP_PORT(80) andAIRPOST_HTTPS_PORT(443, TCP and UDP for HTTP/3), mounts theCaddyfileread-only, and keeps certificates incaddy-dataandcaddy-config. Itsdepends_onentries arerequired: false, so it starts whichever components are on.
The airpost network has a fixed subnet (AIRPOST_SUBNET, default 172.31.86.0/24) so the gateway can trust it as a proxy range.
The image
The Dockerfile has three stages:
web(node:22-bookworm-slim) runsnpm ciandVITE_AIRPOST_ENGINE=gateway npm run buildinapps/web.build(rust:1.92-slim-bookworm) runscargo build --release --lockedforairpost-engine,airpost-gateway,airpost-backend,airpost-mcpandairpost, and writes third-party notices.- The runtime is
gcr.io/distroless/cc-debian12:nonroot: no shell, no curl. Binaries go to/usr/local/bin, the web client to/usr/share/airpost/web, licences to/usr/share/doc/airpost.
The image sets these defaults, which the compose file relies on:
| Env | Value |
|---|---|
CONFIG_DIR_PATH, AIRPOST_CONFIG_DIR | /profile |
AIRPOST_ENGINE_KEY_FILE | /keys/engine.key |
AIRPOST_GATEWAY_WEB_ROOT | /usr/share/airpost/web |
AIRPOST_GATEWAY_BIND | 0.0.0.0:5180 |
AIRPOST_DATA_DIR, AIRPOST_BIND | /data, 0.0.0.0:5101 (backend) |
/profile, /keys, /data and /backups are created empty and owned by uid 65532, so fresh volumes are writable. To build it by hand from the repository root:
docker build -f deploy/server/Dockerfile -t airpost-server .
An image built without the SOURCE_URL and SOURCE_TAG build args says in /usr/share/doc/airpost/SOURCE.txt that it must not be published.
mcp.json
{
"accessLevel": "read-only",
"enabledAccounts": {},
"http": {"enabled": true, "port": 2587}
}
Edit it on the host and run docker compose restart mcp. See Access levels.
Setup
You need a Linux machine with Docker, a DNS name pointing at it, and ports 80 and 443 open.
Get the compose files
Copy deploy/server/ from the repository and change into it.
Configure
cp .env.example .env
Set AIRPOST_DOMAIN, AIRPOST_VERSION and COMPOSE_PROFILES (default web,proxy; add mcp to run it). All variables are in Configuration.
Start it
Check it
docker compose ps shows each service healthy. docker compose exec engine airpost status lists the engine and its accounts (none yet).
Add an account and pair a browser
See Adding mail accounts and Pairing browsers.
Trying it without a domain
On one machine, without TLS:
AIRPOST_DOMAIN=127.0.0.1 \
AIRPOST_PUBLIC_URL=http://127.0.0.1:5180 \
COMPOSE_PROFILES=web \
docker compose -f compose.yaml -f compose.own-proxy.yaml up -d
The web client is then at http://127.0.0.1:5180.
Turning components on and off
Add a profile to COMPOSE_PROFILES and run docker compose up -d. To turn one off, take it out and remove its container, for example docker compose rm -sf mcp.
Adding mail accounts
Use the airpost CLI in the engine’s container. For IMAP, Airpost finds the servers for most providers; --imap-host, --smtp-host and the other flags of airpost account add --help override them:
docker compose exec engine airpost account add you@example.com
It asks for the password (or reads it with --password-stdin), tests the account and stores it.
Gmail and Microsoft accounts sign in in a browser, which on a server runs on another computer:
docker compose exec engine airpost account add you@gmail.com --provider gmail --paste
Open the address it prints, sign in, and paste back the http://127.0.0.1:12141/?code=… address the browser ends on (that page doesn’t load; that’s expected). --provider office365 and outlook work the same way.
A browser paired with --admin can also add IMAP accounts in the web client’s Settings > Accounts.
docker compose exec engine airpost status shows each account’s state. docker compose exec engine airpost logs <email> -f follows its log.
TLS
With the proxy profile, Caddy gets a certificate for AIRPOST_DOMAIN and routes one hostname to every component (deploy/server/Caddyfile):
| Path | Goes to |
|---|---|
/mcp | mcp:2587, unbuffered |
/ping, /airpost/*, /metadata/*, /deltas/*, /t/* | the backend (answers 502 while it’s off) |
| everything else | gateway:5180: the web client and /gateway/* |
Your own reverse proxy
Leave proxy out of COMPOSE_PROFILES and add the compose.own-proxy.yaml override:
docker compose -f compose.yaml -f compose.own-proxy.yaml up -d
The gateway is then on 127.0.0.1:5180 and MCP on 127.0.0.1:2587. Route /mcp to MCP without buffering, and everything else to the gateway. The gateway needs WebSocket upgrades and the original Host header, which it checks.
airpost.example.com {
handle /mcp {
reverse_proxy 127.0.0.1:2587 {
flush_interval -1
}
}
handle {
reverse_proxy 127.0.0.1:5180
}
}
Caddy forwards WebSocket upgrades, Host and X-Forwarded-For by default.
The gateway pings every WebSocket every 30 seconds and closes one that has sent nothing for 45 seconds, so a proxy read timeout of 60 seconds (nginx’s default) is enough; 1h above is a margin. Uploads go up to 25 MiB, so the proxy must accept bodies that large.
The gateway reads X-Forwarded-For for its pairing rate limits only from addresses in AIRPOST_TRUSTED_PROXIES. The compose file sets that to the compose network, which covers Caddy and a host proxy reaching the published port. See Security.
Without Docker
deploy/systemd/ has no units for the engine or the gateway. To run them as services on a Linux machine without Docker, install the CLI and use its unit commands: airpost engine install for a detached engine (Engine) and airpost gateway install --public-url https://<domain> for the gateway (Services). These install systemd user units, so on a server run loginctl enable-linger "$USER" once to keep them running after you log out. Put a TLS proxy in front as above.
Backups
| Volume | Holds |
|---|---|
profile | The mail database, settings, signatures, rules, accounts and their encrypted credentials (secrets.enc), paired browsers (gateway/devices.json), the MCP token and audit log |
engine-key | engine.key, which decrypts secrets.enc. Back it up separately from profile. |
caddy-data | Certificates. Caddy gets new ones if you lose it. |
Mail itself stays on your mail servers. Without profile you add the accounts again and Airpost syncs from scratch. A profile backup without the matching key restores mail and settings, but every account needs its password or sign-in again.
For a consistent copy of the profile, stop the engine first. The gateway and MCP lose the engine while it’s stopped and reconnect when it’s back:
docker compose stop engine
docker run --rm -v airpost-server_profile:/p:ro -v "$PWD":/out alpine \
tar czf /out/airpost-profile.tgz -C /p .
docker run --rm -v airpost-server_engine-key:/k:ro -v "$PWD":/out alpine \
tar czf /out/airpost-engine-key.tgz -C /k .
docker compose start engine
Store airpost-engine-key.tgz somewhere other than the profile archive.
Restoring
On a fresh host, create the volumes with docker compose create, then unpack both archives into them as uid 65532 and start:
docker compose create
docker run --rm -v airpost-server_profile:/p -v "$PWD":/in alpine \
sh -c 'tar xzf /in/airpost-profile.tgz -C /p && chown -R 65532:65532 /p'
docker run --rm -v airpost-server_engine-key:/k -v "$PWD":/in alpine \
sh -c 'tar xzf /in/airpost-engine-key.tgz -C /k && chown -R 65532:65532 /k'
docker compose up -d
Paired browsers keep working if the public URL is unchanged.
Upgrades
Set the new AIRPOST_VERSION in .env, then:
docker compose pull
docker compose up -d
docker compose ps
Compose recreates each container on the new image; the engine starts first and the gateway and MCP wait until it is healthy. From a checkout, git pull and rerun the compose.build.yaml command with --build.
The engine migrates its database when it starts and doesn’t keep a copy of the old one. Back up profile first if you might roll back. Rolling back means restoring that backup, then setting the old AIRPOST_VERSION.
Read the release notes before upgrading across several versions. Browsers reload the web client on their next visit.
Health and logs
Each health check is a command in the image, since there is no shell or curl:
| Service | Check | Fails when |
|---|---|---|
engine | airpost status | No engine answers on the profile’s socket (exit code 3) |
gateway | airpost-gateway healthcheck | The gateway doesn’t answer GET /healthz. It reports the gateway, not the engine. |
mcp | airpost-mcp healthcheck | MCP doesn’t answer |
docker compose ps shows the state of each. To alert on it, watch docker inspect --format '{{.State.Health.Status}}' airpost-server-engine-1 (or your monitoring system’s Docker integration). From outside, a request to https://<domain>/healthz checks Caddy and the gateway together.
Where logs go:
| What | Command |
|---|---|
| An account’s sync, send and auth | docker compose exec engine airpost logs <email>; add -f to follow, -n 200 for more lines |
| Gateway: pairing, refused hosts, sessions | docker compose logs -f gateway |
| MCP server | docker compose logs -f mcp |
| MCP tool calls | mcp-audit.log in the profile, one JSON object per line |
| TLS and routing | docker compose logs -f caddy |
The engine writes its logs into the profile, not to Docker. The gateway and MCP log to stderr; set RUST_LOG=debug in their environment for more.
More than one person
A profile belongs to one person. To host a second person on the same machine, run a second Compose project from a copy of deploy/server/ with its own .env:
cp -r deploy/server airpost-bob && cd airpost-bob
cp .env.example .env # AIRPOST_DOMAIN=bob.example.com, AIRPOST_SUBNET=172.31.87.0/24
docker compose -p airpost-bob -f compose.yaml -f compose.own-proxy.yaml up -d
-p gives it its own volumes (airpost-bob_profile, …). Each project needs its own subnet and, with compose.own-proxy.yaml, its own AIRPOST_GATEWAY_PORT and AIRPOST_MCP_PORT. Only one Caddy can own ports 80 and 443, so with more than one project, put one proxy on the host and route each domain to its project’s ports.