Cluster Deployment (infra) #

TsubameMail deploys as an isolated Cell orchestrated by Docker Compose under infra/deploy/cell/ alongside host preparation scripts under infra/deploy/vm/ and cloud templates under infra/deploy/aws/.

Service Topology & Ports #

ServiceInternal / Edge NetworkExposed PortsRole
https-proxy (Nginx 1.27)edge_net443Terminates TLS 1.2/1.3 for admin.<your-domain>, console.<your-domain>, mail.<your-domain>
control-backenddedge_net, cell_net127.0.0.1:8080Control API, Platform Identity (/v1/platform/*), Ops, Alerts, Recovery
identitydcell_net50051 (gRPC)Password hashing (IDENTITY_PEPPER), App Passwords, Auth/Authz gRPC
tenant-configdcell_net50052 (gRPC), 8082Tenant directory, domain verification, DKIM keystore
smtp-inedge_net, cell_net25, 465, 587Inbound MX (25) + authenticated SMTP submission (465 SMTPS / 587 STARTTLS)
imapdedge_net, cell_net143, 993IMAP4rev1 (143 STARTTLS / 993 IMAPS)
pop3dedge_net, cell_net110, 995POP3 (110 STLS / 995 POP3S)
mta-outedge_net, cell_net50053 (gRPC), 8088Outbound DKIM-signed delivery & optional SmartHost relay
scannerdscanner_isolated_netinternal onlyAir-gapped attachment malware scanner (no default route / no internet)
mail-workercell_net, scanner_isolated_netinternal onlyQueue consumer moving staged intake items to durable storage
postgres (PG 17)cell_netinternal onlyPersistence (disabled when overriding with AWS RDS)

Deployment Steps #

  1. Prepare Environment & Secrets: Copy the parameterized template and generate high-entropy secrets (>= 32 bytes) for every GENERATE_ME field:
bash
cd infra/deploy/cell
cp .env.cell.single-node.example .env
chmod 600 .env
  1. Prepare Host Data Permissions & Outbound Submission Credential: Ensure CELL_DATA_ROOT (/var/lib/tsubame/cell) and CELL_OUTBOUND_CREDENTIAL_FILE exist with 0600 permissions and >= 32 printable bytes.
  2. Build Images (Offline-Capable):
bash
./build-images.sh --platform linux/amd64
  1. Validate & Launch:
bash
python3 validate-single-node-env.py .env
docker compose -f docker-compose.cell.yml -f docker-compose.cell.single-node.yml --env-file .env up -d --no-build
WARNING

smtp-in in single-node or production mode verifies that PostgreSQL has fsync=on and synchronous_commit=on before running migrations. Never disable fsync in production.