cadcad-discourse-forum/SPEC.md

cadCAD Discourse Forum - Deployment Spec

Summary

Deploy a self-hosted Discourse forum on Netcup RS 8000, initially at cadcad-forum.jeffemmett.com (temporary domain), to be switched to community.cadcad.org once DNS is coordinated. An existing Discourse backup will be imported later.

Architecture Decision: Official Discourse Docker

Chosen approach: Official Discourse Docker (discourse/discourse_docker)

Why official over alternatives?

Criteria	Official	nfrastack (alternative)
Backup import	Best (native)	Untested
Long-term support	Discourse team	Community
Plugin management	Easy (app.yml)	Env vars
Traefik integration	Requires config tweaks	Native
Docker-compose native	No (custom launcher)	Yes

Backup compatibility is the deciding factor since we need to import an existing community.cadcad.org backup later. The official approach is the only one guaranteed to handle this reliably.

Trade-off accepted

The official Discourse Docker uses a custom ./launcher script instead of standard docker-compose. This breaks the pattern used by other services on the stack, but is necessary for reliable backup import/restore.

Technical Details

Infrastructure

• Server: Netcup RS 8000 (64GB RAM, 20 cores)
• Container type: Monolithic (PostgreSQL + Redis + Discourse in one container)
• Memory limit: 2GB container + 2GB swap (sufficient for <1k users in steady state)
• Temp domain: cadcad-forum.jeffemmett.com
• Final domain: community.cadcad.org (DNS controlled by someone else)

Routing

Internet → Cloudflare Tunnel → Traefik (:80) → Discourse container (:80 internal)

Traefik integration via Docker labels in app.yml:

• Disable SSL templates (Cloudflare handles TLS)
• Don't expose ports directly (Traefik routes traffic)
• Connect to traefik-public network via docker_args

Email

• Deferred for initial setup
• Will configure SMTP later (Resend or another provider)
• Discourse will warn about missing email but will function for admin access

Storage

• Data stored in /opt/discourse/shared/standalone/ on Netcup
• PostgreSQL data, Redis data, uploads, backups all within the container's shared directory
• Repo at /opt/discourse/ contains config only (not data)

Deployment Steps

1. Create repo with config files locally at /home/jeffe/Github/cadcad-discourse-forum
2. Clone to Netcup at /opt/discourse/
3. Install official Discourse Docker (discourse_docker launcher)
4. Configure app.yml with Traefik labels, no SSL, 2GB memory limit
5. Add Cloudflare tunnel hostname for cadcad-forum.jeffemmett.com
6. Bootstrap and start Discourse
7. Verify forum is accessible at cadcad-forum.jeffemmett.com

Files in This Repo

cadcad-discourse-forum/
├── SPEC.md                    # This file
├── README.md                  # Deployment instructions
├── app.yml                    # Discourse container config (copied to /opt/discourse/containers/)
├── .env.example               # Environment variable template
└── scripts/
    ├── install.sh             # Initial setup script (run on Netcup)
    └── restore-backup.sh      # Backup import script (for later)

Migration Plan (Later)

1. Obtain .tar.gz backup from existing community.cadcad.org admin panel
2. Upload to /opt/discourse/shared/standalone/backups/default/
3. Run restore: ./launcher enter app → discourse restore <filename>
4. Coordinate DNS change: community.cadcad.org CNAME → tunnel
5. Update app.yml hostname and rebuild

Out of Scope

• Email configuration (deferred)
• SSO/OAuth integration
• Custom plugins (can be added later via app.yml)
• CDN configuration
• Automated backups (Discourse has built-in scheduled backups)

Open Questions

• Which email provider to use when ready (Resend, Mailgun, etc.)
• Who to coordinate with for cadcad.org DNS
• Whether any specific Discourse plugins are needed from the existing instance