first commit
This commit is contained in:
commit
cce9a8c9ba
73 changed files with 8665 additions and 0 deletions
244
DEPLOYMENT.md
Normal file
244
DEPLOYMENT.md
Normal file
|
|
@ -0,0 +1,244 @@
|
|||
# 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
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```bash
|
||||
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 |
|
||||
|
||||
```bash
|
||||
curl -fsS http://127.0.0.1:8000/health
|
||||
docker compose ps
|
||||
docker compose logs -f caddy
|
||||
```
|
||||
|
||||
## Environment (`.env` at repo root)
|
||||
|
||||
### Required
|
||||
|
||||
```env
|
||||
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)
|
||||
|
||||
```env
|
||||
# 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):
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue