Merge branch 'docs/adopt-decisions'
This commit is contained in:
+12
-9
@@ -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
@@ -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
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user