Docs: adopt builds next to the install and switches over; adopt --undo (decisions 25-26)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-05 13:51:08 +02:00
co-authored by Claude Opus 5.5
parent 8032a5d9e2
commit 4e58c5c07e
3 changed files with 46 additions and 30 deletions
+12 -9
View File
@@ -159,7 +159,7 @@ Secrets stay in each product's own `.env`, never in `church.env`.
| `status [<church>]` | Yes: version from `/health`, latest tag, DB, jobs, last backup |
| `install <church> --products events --domain …` | Yes, for Events only (from today's `install.sh`: Node 24, PostgreSQL, PM2, nginx, certbot); it writes `church.env` |
| `adopt <church> --events-dir …` | Yes (section 5) |
| `adopt <church> --undo` | **New, proposed:** goes back to the old folder and the 2.1.x it ran, within the days the old folder is kept |
| `adopt <church> --undo` | Yes (decision 26): goes back to the old folder and the 2.1.x it ran, within the days the old folder is kept |
| `add <church> <product>` | **Later** (phase 3), when there's a second product to add |
**Requirement check** (decision 24): before anything is touched, read the target version's
@@ -175,8 +175,8 @@ summary lists each product as updated, rolled back or not reached.
## 5. `crosscode adopt` (once per existing install)
**Proposed change to ROADMAP §8:** build the new checkout **next to** the running install, then
switch over, instead of moving the running folder. Moving the folder underneath running PM2
**Decided 2026-11-05 (ROADMAP decision 25):** build the new checkout **next to** the running
install, then switch over, instead of moving the running folder. Moving the folder underneath running PM2
processes breaks anything they read from disk later (Next.js pages, uploads), so the site would
be down for the whole build. Building next to it keeps the old install untouched, which makes
rolling back simply "start the old one again".
@@ -243,10 +243,13 @@ database or its name.
root [HANDOVER.md](./HANDOVER.md) updated with 1b done and 1c (2.3.0, authenticator app 2FA)
next.
## Open questions
## Decisions
1. Build next to the old install and switch over (section 5, recommended), or move the folder as
ROADMAP §8 says? If the switch-over is agreed, §8 gets updated to match.
2. `adopt --undo`: build it (recommended; it's small once the old folder is kept) or not?
3. Do any Events backend tests need a database, which would affect the root `npm run check`?
(Answered while doing section 2.)
1. `adopt` builds next to the old install and switches over (section 5); ROADMAP §8 updated to
match (decision 25).
2. `adopt --undo` is built (decision 26).
## Still open
- Do any Events backend tests need a database, which would affect the root `npm run check`?
(Answered while doing section 2.)
+4 -3
View File
@@ -25,7 +25,7 @@ for each phase. They moved here from `hope-events/docs/` on 2026-11-05.
|-------|------|-------|
| 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04 (`contracts@1.0.0`, `contracts@1.1.0`). Not published to a registry (decision 22): the Hub gets a packed release committed to its repo |
| 1 | Hub 2.0.0 | **Released** 2026-11-05 (`events-hub` `v2.0.0`; `docs/HUB-2.0-PLAN.md` there). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). crosscode-site's address prices are merged, **not deployed yet** |
| 1b | Cross Events 2.2.0: moves here as `apps/events`, `crosscode` script | **Next.** Planned in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md) |
| 1b | Cross Events 2.2.0: moves here as `apps/events`, `crosscode` script | **Next.** Planned and decided in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md) |
| 1c | Cross Events 2.3.0: authenticator app 2FA (TOTP + recovery codes) | Not started (`TwoFactorMethod` enum in Events' `prisma/schema.prisma`) |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | Not started. Events keeps speaking protocol 1 until then |
| 3–7 | Accounts 1.0.0 → Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started |
@@ -34,8 +34,9 @@ for each phase. They moved here from `hope-events/docs/` on 2026-11-05.
1. **Deploy Hub 2.0.0** and **crosscode-site** (the address prices). This finishes phase 1 and is
needed before 2.2.0, because Hub 1.7 can't see `events@…` tags.
2. **Cross Events 2.2.0**: [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). Its open questions (how
`adopt` switches over, `adopt --undo`) are settled before the script is written.
2. **Cross Events 2.2.0**: [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). Decided 2026-11-05:
`adopt` builds next to the running install and switches over, and `adopt --undo` is built
(ROADMAP decisions 25–26).
3. **Cross Events 2.3.0** (authenticator app 2FA), then 2.4.0, as in ROADMAP §9.
## Things to remember across phases
+30 -18
View File
@@ -518,6 +518,7 @@ own migrations), so a Website install never builds Events.
| `crosscode install <church> --products events,website --domain … ` | A new church (from today's `install.sh`): Accounts always, plus the products named; databases, `.env` files, PM2, nginx and certificates; prints the DNS records needed |
| `crosscode add <church> app` | Adds a product to an existing church |
| `crosscode adopt <church> --events-dir /var/www/<old folder>` | Once per existing Cross Events install: moves it onto the monorepo and into `/var/www/sites/<church>/events` (below) |
| `crosscode adopt <church> --undo` | Goes back to the old folder and the 2.1.x it ran, while the old folder is kept (14 days) |
Before Accounts exists (until phase 3), "always Accounts" is skipped for churches that don't have
it yet.
@@ -537,28 +538,32 @@ it yet.
reached.
**Moving existing Cross Events installs (Events 2.2.0, `crosscode adopt`).** Once per server
install, run by Joshua. It:
install, run by Joshua. **The new checkout is built next to the running install, then PM2 switches
over** (decided 2026-11-05, decision 25). The running folder is never moved, because moving it
underneath PM2 would break everything the running processes read from disk later, so the site
would be down for the whole build. The steps are in
[EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md) §5. In short:
1. Moves the install's folder from `/var/www/<old folder>` to `/var/www/sites/<church>/events`
(skipped if it's already there, e.g. moved by hand) and writes `church.env`.
2. Changes the checkout's remote to `crosscode-platform` and moves the install's own files to
the new paths: `backend/.env` → `apps/events/backend/.env`, likewise the frontend `.env`,
`backend/public/uploads/`, `backend/backups/`, `backend/data/*.json`, and
`ecosystem.config.js` with its `cwd` paths updated.
3. Checks out `events@2.2.0`, builds, and **re-registers the PM2 processes** under their existing
names from the new folder (`pm2 delete` + `pm2 start` + `pm2 save`: PM2 remembers the folder a
process was started from, so a reload isn't enough after a move).
1. Checks: the old folder is a `hope-events` checkout at a `v2.1.x` tag with no files changed by
hand. Reads the PM2 names, ports and database name the install already has, and writes
`church.env`.
2. A fresh checkout of `crosscode-platform` at `events@2.2.0` in
`/var/www/sites/<church>/events`. The install's own files are copied into `apps/events/`:
`backend/.env` and the frontend `.env`, `backend/data/*.json`, `backend/backups/`,
`ecosystem.config.js` (absolute `cwd`s rewritten), and the uploads (`rsync`). Then it builds.
The old install keeps serving throughout.
3. Switch over (a few seconds of downtime): database backup → a final `rsync` of the uploads and
data files → no pending migrations → `pm2 delete` + `pm2 start` from the new folder +
`pm2 save` (PM2 remembers the folder a process was started from, so a reload isn't enough) →
`/health` reports 2.2.0. If that fails, PM2 starts from the old folder again, which was never
changed.
4. The old folder is kept as `<old>.pre-2.2.0` for 14 days. **`crosscode adopt <church> --undo`**
(decision 26) goes back to it within that time, copying back uploads added since.
`crosscode status` reminds you to remove it afterwards.
The PM2 names, nginx config (it only proxies to ports, so it doesn't change when the folder
moves), database and its name stay the same. If anything fails it moves everything back, returns
to the `hope-events` remote and the version it was on, and starts PM2 from the old folder again.
The PM2 names, nginx config (it only proxies to ports), database and its name stay the same.
Installs that haven't moved yet keep working with `deploy.sh` on the archived repo.
**Moving a folder by hand before 2.2.0** works too: move it into `/var/www/sites/<church>/events`,
then `pm2 delete` its two processes, `pm2 start ecosystem.config.js` from the new folder and
`pm2 save`. `deploy.sh` works from wherever the install is, and `adopt` later sees it's already in
place.
---
## 9. Build order
@@ -773,6 +778,13 @@ ranking.
| 23 | Deploying | **One `crosscode` script** for every product, with every church under `/var/www/sites/<church>/<product>`: `crosscode deploy <church> [events] [website] [app]` always updates Accounts and then the products named, in a fixed order, each rolled back on its own if it fails. Still git checkouts of tags, still run by Joshua; the Hub never deploys (§8) |
| 24 | Product requirements | A release can require a minimum version of a sibling (`— requires accounts 1.2.0` in `WHATS-NEW.md`). The Hub **disables Request update** until it's met, and the script refuses to deploy without it (§5, §8) |
**Added 2026-11-05**
| # | Question | Decision |
|---|----------|----------|
| 25 | Moving existing Events installs | `crosscode adopt` **builds the new checkout next to the running install and switches PM2 over** (seconds of downtime) instead of moving the running folder; the old folder is untouched, so a failure just starts it again (§8) |
| 26 | Undoing a move | **`crosscode adopt <church> --undo`** goes back to the old folder and its 2.1.x while it's kept (14 days) (§8) |
## Still open
Nothing. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the