Suyash091/agentic.email
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agentic.email/DEPLOYMENT.md
debu-2 cce9a8c9ba first commit
2026-10-03 21:14:44 +05:30

7 KiB
Raw Blame History

Deployment guide

Agmail runs as one Docker Compose stack on a mail VPS (port 25 open): Caddy (HTTPS), frontend, backend, PostgreSQL, MongoDB, and Postfix (inbound + outbound).

The main website at getall.help can stay on another host (e.g. GCP). Only the email stack lives on the mail VPS:

Hostname Points to Purpose
getall.help GCP / main site IP Marketing / main app (unchanged)
email.getall.help Mail VPS public IP Agmail web UI (Caddy → frontend)
mail.getall.help Mail VPS public IP Postfix :25 (inbound + outbound)
@getall.help MX mail.getall.help Delivers mail to the VPS

User addresses remain user@getall.help.

Architecture

Browser ──HTTPS──► email.getall.help (Caddy :443)
                      └──► frontend ──► backend ──SMTP──► smtp:25 (Postfix outbound)

Internet ──SMTP:25──► mail.getall.help (Postfix)
                         ├── inbound  → backend:2525 → GCS + MongoDB
                         └── outbound ← backend (Docker mynetworks)

Quick start

cp .env.example .env
# Edit .env — see Environment section below
docker compose up -d --build

Open https://email.getall.help after DNS and TLS are ready.

Service Host port Purpose
caddy 80, 443 Public HTTPS entrypoint
frontend 127.0.0.1:8080 Local debug only
backend 127.0.0.1:8000 API / health (local)
smtp 25 Inbound + outbound Postfix 
curl -fsS http://127.0.0.1:8000/health
docker compose ps
docker compose logs -f caddy

Environment (.env at repo root)

Required

JWT_SECRET=<openssl rand -hex 32>
POSTGRES_PASSWORD="<strong password>"
MONGO_ROOT_PASSWORD="<strong password>"
GCS_RAW_MIME_BUCKET=<private bucket>
GCS_PROJECT=<gcp project id>
GCP_CREDENTIALS_FILE=./midyear-karma-470610-i1-da5334d20acc.json
CADDY_ACME_EMAIL=admin@getall.help
CORS_ORIGINS=["https://email.getall.help"]

Quote values that contain #.

GCP_CREDENTIALS_FILE is relative to deploy/app/, not the repo root.

Outbound uses the Docker Postfix service by default (SMTP_HOST=smtp, SMTP_PORT=25, SMTP_USE_TLS=false). No Amazon SES credentials are required.

Split-domain settings (mail VPS)

# User mailboxes are still @getall.help
PLATFORM_DOMAIN=getall.help

# Web UI on this host (Caddy terminates TLS here)
APP_PUBLIC_HOST=email.getall.help
CADDY_ACME_EMAIL=admin@getall.help

# Postfix hostname (inbound + outbound)
MAIL_HOSTNAME=mail.getall.help
MAIL_DOMAIN=getall.help
INBOUND_DOMAINS=getall.help
SMTP_PUBLIC_HOST=mail.getall.help
SMTP_HOST=smtp
SMTP_PORT=25
SMTP_USE_TLS=false

# Same-host Docker defaults (usually leave as-is)
BACKEND_INGEST_HOST=backend
BACKEND_INGEST_PORT=2525
INBOUND_ALLOWED_CIDRS=["172.16.0.0/12","127.0.0.0/8"]
INBOUND_SMTP_BIND_IP=127.0.0.1

Namecheap DNS changes

Update DNS as follows (<VPS_IP> = public IP of the mail server). Generate the exact rows at https://email.getall.help/smtp-credentials:

Inbound

Type Host Value Notes
A @ main site IP Keep — marketing site
A email <VPS_IP> Web UI
A mail <VPS_IP> Postfix
MX @ 10 mail.getall.help Priority 10

Outbound authentication

Type Host Value Notes
TXT @ v=spf1 mx a ip4:<VPS_IP> ~all SPF for @getall.help mail
TXT _spf v=spf1 ip4:<VPS_IP> ~all Required — company domains SPF-include this
TXT agmail._domainkey app DKIM public key From /smtp-credentials
TXT _dmarc v=DMARC1; p=quarantine; rua=mailto:dmarc@getall.help One record only

Remove any old Amazon SES Easy DKIM CNAMEs and include:amazonses.com from SPF.

Firewall / security group

Port Source Purpose
443 0.0.0.0/0 HTTPS web UI
80 0.0.0.0/0 HTTP → HTTPS redirect (Caddy)
25 0.0.0.0/0 Inbound mail (+ outbound egress)

Do not expose 5432, 27017, 8000, or 2525 publicly.

Confirm egress on port 25 is allowed (required for delivery to Gmail/Outlook):

nc -vz -w 5 gmail-smtp-in.l.google.com 25

Reverse DNS (PTR) — required for Gmail/Outlook

Major receivers expect your VPS IP reverse DNS to match mail.getall.help.

dig +short -x YOUR_VPS_IP
# Good: mail.getall.help.

Set PTR in your VPS provider panel (is*hosting: client area → network / rDNS, or open a support ticket) to mail.getall.help.

STARTTLS on Postfix (port 25)

Gmail/Zoho use STARTTLS. Postfix generates a cert on first boot. After rebuild:

printf 'EHLO test\r\nSTARTTLS\r\n' | nc mail.getall.help 25
# expect: 220 Ready to start TLS   (not 454 TLS not available)

Caddy / TLS

Caddy obtains Let's Encrypt certificates automatically when:

  1. APP_PUBLIC_HOST=email.getall.help resolves to this server's public IP
  2. Ports 80 and 443 are open
  3. CADDY_ACME_EMAIL is set in .env

Config: deploy/caddy/Caddyfile → reverse-proxies to frontend:80.

Smoke test

# HTTPS UI
curl -fsSI https://email.getall.help/health

# Inbound mail (account must exist)
swaks \
  --server mail.getall.help:25 \
  --from sender@example.com \
  --to existing-user@getall.help \
  --header "Subject: inbound smoke test" \
  --body "Verify delivery"

# Outbound queue after sending from the UI
docker exec agmail-smtp postqueue -p
curl -fsS http://127.0.0.1:8000/health

Operations

docker compose logs -f caddy backend smtp
docker compose restart caddy
docker exec agmail-smtp postqueue -p

Persistent volumes: postgres_data, mongo_data, smtp_queue, caddy_data.

TLS troubleshooting (SSL_ERROR_INTERNAL_ERROR_ALERT)

This means Caddy is listening on 443 but does not have a valid certificate (Let's Encrypt issuance failed or left bad state in caddy_data).

On the mail server:

cd /opt/apps/agentic_email

# 1. Confirm .env has a real contact email (use your Gmail if unsure)
grep CADDY_ACME_EMAIL .env
grep APP_PUBLIC_HOST .env
# APP_PUBLIC_HOST=email.getall.help
# CADDY_ACME_EMAIL=you@gmail.com

# 2. Check Caddy logs for ACME errors
docker compose logs caddy --tail 80

# 3. Reset Caddy cert storage and recreate
docker compose stop caddy
docker volume rm agentic_email_caddy_data 2>/dev/null || docker volume rm email_caddy_data
docker compose up -d --build caddy
docker compose logs -f caddy

Wait 30–60 seconds, then test:

curl -fsSI https://email.getall.help/

Requirements for Let's Encrypt:

  • email.getall.help A record → this server's public IP
  • Firewall allows inbound TCP 80 and 443 from 0.0.0.0/0
  • CADDY_ACME_EMAIL set in .env

If logs show rate limits, wait an hour or use a staging CA temporarily.

API reference

  • GET /health — service checks (also proxied at /health on the web host)
  • POST /api/v1/dns-setup/preview — DNS generator (HTTP Basic Auth)