Cloudron deployment plan

2026-04-22 18:54:32 -06:00
parent c7f22a0990
commit 4d066dad0e
5 changed files with 220 additions and 22 deletions
@@ -0,0 +1,154 @@
+# Backend deploy — admin handoff
+
+This is the list of access, environment variables, and platform decisions
+needed to deploy CommunityRule (the new Next.js + Postgres app in this
+repo) onto MEDLab's Cloudron. Hand it to the Cloudron admin; once they
+confirm what is checked below, the actual deploy happens in the
+follow-up tickets listed in §8.
+
+## 1. Context
+
+- This app **replaces** the old Express + MySQL backend at
+  [`CommunityRule/CommunityRuleBackend`](https://git.medlab.host/CommunityRule/CommunityRuleBackend).
+- It is packaged as a real Cloudron app (Docker image +
+  `CloudronManifest.json`). No `/app/data` drop-in. No `run.sh`
+  watchdog — Cloudron's container supervisor handles restarts.
+- **Greenfield Postgres.** No data migration from the old MySQL addon.
+  Old auth (4-digit OTP in `email_otp`) is replaced by hashed
+  magic-link tokens; old API and `rules` / `version_history` tables do
+  not map to anything in the new app.
+
+## 2. Access I need
+
+Check off as granted:
+
+- [ ] **Cloudron admin login** for the MEDLab instance, or "deploy
+  app" capability scoped to one app slot.
+- [ ] **Container registry credentials** — read/write to wherever
+  images get pushed (Docker Hub, GHCR, MEDLab self-hosted registry —
+  admin's choice; see §6).
+- [ ] **DNS** — ability to add/edit a subdomain record pointing at the
+  Cloudron host, or confirmation that admin will add the records I
+  specify.
+- [ ] **`cloudron` CLI access** from my workstation (token-based; no
+  SSH needed for normal ops).
+- [ ] **Cloudron app log access** — web UI is fine; SSH only if web
+  logs aren't enough.
+- [ ] **Read access to the existing legacy app's Cloudron config** so
+  I can confirm domain / cert / SMTP setup before cutover.
+
+## 3. Environment variables
+
+### Cloudron auto-injects (admin: confirm the addons are enabled)
+
+- `CLOUDRON_POSTGRESQL_URL` — from the **postgresql** addon. The app
+  reads `DATABASE_URL`; bridging is a small in-app code change (see
+  §8 ticket 1).
+- `CLOUDRON_MAIL_SMTP_SERVER` / `_PORT` / `_USERNAME` / `_PASSWORD` —
+  from the **sendmail** addon. The app reads `SMTP_URL`; bridged the
+  same way.
+
+### I set manually via `cloudron configure --app <id> --set-env`
+
+- `SESSION_SECRET` — long random (`openssl rand -hex 32`). Required,
+  ≥ 16 chars. Rotating it logs everyone out.
+- `SMTP_FROM` — visible "From:" address on sign-in emails. Cloudron
+  does **not** inject this. Recommend `hello@communityrule.info` (same
+  as the old service) unless admin wants a new address.
+- `NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true` — turns on Postgres draft
+  persistence for signed-in users. Recommended for production.
+
+## 4. Platform settings to confirm
+
+- Container `httpPort`: **3000** (matches [`Dockerfile`](../../Dockerfile)
+  `ENV PORT=3000`).
+- Health-check path: **`/api/health`**
+  ([`app/api/health/route.ts`](../../app/api/health/route.ts) returns
+  `200 {"ok":true,"database":"connected"}` when healthy, `503`
+  otherwise).
+- Memory limit: start at **512 MB**; raise if Next.js standalone OOMs
+  under load.
+- Backups: confirm Cloudron's daily snapshot is on for both this app
+  and its postgresql addon.
+- TLS, DNS, SPF/DKIM: handled by Cloudron for the chosen subdomain —
+  confirm.
+
+## 5. Decisions I need from admin
+
+1. **Subdomains** for staging and production. Default proposal:
+   `staging-app.communityrule.info` + `app.communityrule.info`.
+2. **Sender address** — reuse legacy `hello@communityrule.info`, or
+   pick a new one?
+3. **Container registry** — MEDLab self-hosted, Docker Hub (under
+   what org), or GHCR?
+4. **Cutover overlap** — how many days should the old service keep
+   running in parallel before we uninstall it?
+5. **Backup retention** beyond Cloudron defaults? (If "defaults are
+   fine," say so.)
+
+## 6. What is intentionally NOT in this doc
+
+So admin doesn't expect more than this scope:
+
+- The deploy runbook itself (build / push / install / migrate / smoke
+  / rollback) — written **after** access in §2 is granted; see §8
+  ticket 5.
+- Code changes to bridge `CLOUDRON_*` env vars to `DATABASE_URL` /
+  `SMTP_URL` — I do those locally and ship the image with bridging
+  built in; see §8 ticket 1.
+- Decommissioning the legacy Express/MySQL service — does not happen
+  until the new app is green in production; see §8 ticket 6.
+
+## 7. Old vs new backend deltas
+
+So nothing surprises admin or users at cutover:
+
+- Old addons: **MySQL + sendmail**. New addons: **postgresql +
+  sendmail + localstorage**. Different DB addon entirely; do not
+  reuse the old one.
+- Old service ran from `/app/data/public/communityRuleBackend` with a
+  30-min `lsof`-based `run.sh` watchdog — not a packaged Cloudron
+  app. New app is a proper Cloudron app; Cloudron supervises it.
+- Old auth = plaintext 4-digit OTP. New auth = magic **link** in
+  email. If users report "I'm not getting a code," remind them to
+  look for a link.
+- Old code hardcoded `from: 'hello@communityrule.info'` in
+  [`controllers/emailController.js`](https://git.medlab.host/CommunityRule/CommunityRuleBackend/raw/branch/master/controllers/emailController.js)
+  because Cloudron does not inject a `MAIL_FROM`. New app reads
+  `SMTP_FROM` — see §3.
+- Old API surface (`/api/send_otp`, `/api/publish_rule`, etc.) and
+  schema (`rules` + `version_history` tables, soft-delete via
+  `deleted` column) **do not overlap**. No data migration.
+
+## 8. Follow-up tickets
+
+All filed in Linear, titled `[Backend] …`, assigned to me, in the
+**Community-rule** team, **Backlog** state.
+
+1. [**CR-96**](https://linear.app/community-rule/issue/CR-96/backend-bridge-cloudron-env-vars-to-canonical-names)
+   — `[Backend] Bridge CLOUDRON_* env vars to canonical names`. No
+   admin dependency; can land now.
+2. [**CR-97**](https://linear.app/community-rule/issue/CR-97/backend-container-image-registry-choose-build-push)
+   — `[Backend] Container image registry: choose, build, push`.
+   Depends on registry decision (§5).
+3. [**CR-98**](https://linear.app/community-rule/issue/CR-98/backend-cloudron-staging-install-smoke)
+   — `[Backend] Cloudron staging install + smoke`. Blocked by CR-96
+   + CR-97; needs Cloudron CLI access + staging DNS.
+4. [**CR-99**](https://linear.app/community-rule/issue/CR-99/backend-cloudron-production-install-dns-cutover)
+   — `[Backend] Cloudron production install + DNS cutover`. Blocked
+   by CR-98 green for the agreed overlap window.
+5. [**CR-100**](https://linear.app/community-rule/issue/CR-100/backend-steady-state-operator-runbook)
+   — `[Backend] Steady-state operator runbook`. Blocked by CR-98
+   (we write it after we've actually done it).
+6. [**CR-101**](https://linear.app/community-rule/issue/CR-101/backend-decommission-legacy-expressmysql-backend)
+   — `[Backend] Decommission legacy Express/MySQL backend`. Blocked
+   by CR-99 + sign-off window. Priority: Low.
+
+## 9. Related docs
+
+- [`docs/guides/backend-roadmap.md`](backend-roadmap.md) §11
+  (environments) and §8 (Prisma migrations policy).
+- [`docs/guides/backend-linear-tickets.md`](backend-linear-tickets.md)
+  Ticket 12 / CR-83 — this doc satisfies it.
+- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — local dev setup
+  (Postgres, magic-link, draft sync).