domain migration

docs/GENTIC_EMAIL_DNS.md

@@ -0,0 +1,101 @@
+# Migrating mail platform DNS to gentic.email
+
+This guide covers DNS changes when moving from `getall.help` to `gentic.email`.
+
+## Architecture (unchanged concept)
+
+| Hostname | Purpose |
+|----------|---------|
+| `gentic.email` | Platform domain — individual users get `@gentic.email` addresses |
+| `email.gentic.email` | Web UI (Caddy HTTPS) |
+| `mail.gentic.email` | Postfix SMTP (inbound :25 + outbound) |
+| `_spf.gentic.email` | Platform SPF include target (TXT on `gentic.email`, host `_spf`) |
+
+Company/custom domains still point **their** MX/SPF/DKIM/DMARC at your shared mail host.
+
+---
+
+## 1. Update server environment
+
+Copy and edit `.env` from `.env.example`:
+
+```env
+PLATFORM_DOMAIN=gentic.email
+PLATFORM_SPF_INCLUDE=_spf.gentic.email
+APP_PUBLIC_HOST=email.gentic.email
+CADDY_ACME_EMAIL=admin@gentic.email
+SMTP_PUBLIC_HOST=mail.gentic.email
+MAIL_HOSTNAME=mail.gentic.email
+MAIL_DOMAIN=gentic.email
+INBOUND_DOMAINS=gentic.email
+CORS_ORIGINS=["https://email.gentic.email"]
+```
+
+Redeploy app + SMTP + Caddy stacks after updating env.
+
+---
+
+## 2. DNS at your registrar (gentic.email zone)
+
+Add or update these records at the **gentic.email** DNS provider:
+
+### Inbound mail + web
+
+| Type | Host | Value | Notes |
+|------|------|-------|-------|
+| **A** | `mail` | `<VPS_PUBLIC_IP>` | Mail server |
+| **A** | `email` | `<VPS_PUBLIC_IP>` | Web UI |
+| **MX** | `@` | `10 mail.gentic.email` | Platform inbox delivery |
+
+### Outbound authentication (platform domain)
+
+| Type | Host | Value |
+|------|------|-------|
+| **TXT** | `_spf` | `v=spf1 ip4:<VPS_PUBLIC_IP> ~all` |
+| **TXT** | `@` | `v=spf1 mx a ip4:<VPS_PUBLIC_IP> ~all` |
+| **TXT** | `agmail._domainkey` | *(from /smtp-credentials page after domain register)* |
+| **TXT** | `_dmarc` | `v=DMARC1; p=quarantine; rua=mailto:dmarc@gentic.email` |
+
+Generate exact DKIM/SPF rows from **https://email.gentic.email/smtp-credentials** once DNS for `email` resolves.
+
+### Reverse DNS (PTR)
+
+Ask your VPS provider to set PTR for `<VPS_PUBLIC_IP>` → `mail.gentic.email`.
+
+---
+
+## 3. Company domain onboarding (new checks)
+
+Each company domain must now publish **five** customer records:
+
+1. **Ownership** — `TXT` `_agmail-verify` = `agmail-verify=<token>` (unique per domain, shown in setup UI)
+2. **MX** → `mail.gentic.email`
+3. **SPF** → `v=spf1 include:_spf.gentic.email ~all`
+4. **DKIM** → `agmail._domainkey` with your generated public key
+5. **DMARC** — must match the exact value in setup (not any pre-existing DMARC)
+
+Blocked domains (`google.com`, etc.) cannot be registered as company domains.
+
+---
+
+## 4. Cutover checklist
+
+1. Lower TTL on old `getall.help` records 24h before (optional).
+2. Publish new `gentic.email` A/MX/TXT records.
+3. Update `.env` and redeploy Docker stacks.
+4. Verify TLS: `curl -fsSI https://email.gentic.email/health`
+5. Verify SMTP banner: `nc mail.gentic.email 25`
+6. Send test mail to `user@gentic.email` and from the app.
+7. Re-verify any active company domains (ownership TXT may be added on next verify).
+
+---
+
+## 5. Old getall.help records
+
+After cutover you can remove or repoint:
+
+- `email.getall.help`, `mail.getall.help` A records
+- `getall.help` MX if it pointed at the mail VPS
+- `_spf.getall.help` if no longer used
+
+Keep old records until you're confident nothing still references `getall.help`.