# 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