15 KiB
Cross Events 2.2.0 — moving into the monorepo
Phase 1b of ROADMAP-v3.md (§8 "Releases and updates", §9; decisions 21, 23, 24). Written 2026-11-05.
What 2.2.0 is: Cross Events moves from joshua/hope-events into this repo as apps/events,
with its git history, and the crosscode script replaces scripts/deploy.sh and
scripts/install.sh. It changes no features. If something breaks, the cause is the move.
Churches see one line in What's new ("Nothing changes for you").
Done when:
events@2.2.0is tagged here, and the Hub lists it under Cross Events.- Every existing install has been moved with
crosscode adoptand reports 2.2.0. hope-eventsis archived.- The test results match 2.1.1's.
Before starting
- Hub 2.0.0 is deployed. Its release sync already reads
events@…tags from this repo, with notes inapps/events/WHATS-NEW.md(events-hub/backend/src/utils/releaseSync.js). It also keeps thehope-eventsv…source for older releases. Hub 1.7 can't seeevents@tags. hope-eventsmainis at 2.1.1 with nothing in flight, and frozen from step 1 on. A fix needed during the move goes in on thehope-eventsside as 2.1.2 and is merged in again (step 1 can be re-run).- Baseline: the result counts of 2.1.1's backend Jest run, frontend build and Playwright e2e run, so step 6 has something to compare against.
git-filter-repoinstalled on the dev machine (pip install git-filter-repo).
1. History: merge it in, with paths rewritten
On a fresh clone, so the working repo is never rewritten:
git clone https://c-git.crosscode.co.za/joshua/hope-events.git events-move
cd events-move
git tag -l | xargs git tag -d # v… tags stay in the archived repo
git filter-repo --to-subdirectory-filter apps/events
cd ../crosscode-platform
git checkout -b move/events
git remote add events-move ../events-move && git fetch events-move main
git merge --allow-unrelated-histories events-move/main \
-m "Cross Events moves into the monorepo (apps/events), from hope-events <last commit hash>"
git remote remove events-move
- Why
filter-reporather thangit subtree add: every old commit then already has itsapps/events/…path, sogit logandgit blameon a file show its whole history without--follow. Commit hashes change. The archived repo keeps the originals, and the merge message names the last one. - Old tags aren't brought over. Bare
v2.1.1tags would be ambiguous in a monorepo, and the Hub reads them from the archived repo. Product tags start atevents@2.2.0.
2. Workspaces and the lockfile
- Root
package.json→"workspaces": ["packages/*", "apps/*", "apps/events/backend", "apps/events/frontend"].apps/eventsitself is covered byapps/*(its root scripts and Playwright). - Rename the packages so workspace names are unique:
@crosscode/events(washope-events),@crosscode/events-backend,@crosscode/events-frontend. Nothing reads the names. The Hub reads the backend'sversion(backend/src/hub/report.js), and that stays. All three go to2.2.0. - One lockfile at the root. Delete
backend/package-lock.jsonandfrontend/package-lock.json, then runnpm installat the root. Versions must not drift: comparenpm ls --allbefore and after (next, react, prisma, @prisma/client, express, typescript, jest, ts-jest, @sentry/nextjs, pg-boss, and anything else resolved differently). Pin anything that moved withoverrides. Keep the existingshell-quoteoverride at the root. - Hoisting traps to check:
- Prisma's
prisma-client-jsgenerates into the hoistednode_modules/.prisma/client. That's fine while Events is the only Prisma app. Accounts (phase 3) must use its own generatoroutput, otherwise the two overwrite each other locally. On servers each checkout builds only one app, so the problem doesn't arise there. Events keeps the default, so no imports change in 2.2.0. - Next.js 16 finds the workspace root from the lockfile. Once the nested lockfiles are gone,
there's no "multiple lockfiles" warning, and
next buildtraces files from the repo root. Check that.nextstill builds toapps/events/frontend/.next, and thatNEXT_DIST_DIR(e2e) still works. @types/node20, TypeScript 5, Jest 30 and ESLint 10 are the same majors on both sides.
- Prisma's
- Lint: the root
eslint .ignoresapps/events/**(add it toglobalIgnores). Events keeps its own configs:frontend/eslint.config.mjs, plustscfor the backend. Moving Events onto the root lint is a later cleanup, not part of 2.2.0. - Root
npm run checkruns Events' scripts through--workspaces --if-present: backendtestandtypecheck, frontendbuild. Make sure the backend tests run with no database, as they do today. If any need one, give them their own script so the rootcheckstays self-contained.
3. Inside apps/events
Paths mostly carry over, because everything in Events is relative to its own folder:
.gitignoremoves toapps/events/.gitignore. Git reads a nested.gitignorerelative to its own folder, so/ecosystem.config.js,backend/public/uploads/,backend/backups/andbackend/data/*.jsonkeep working unchanged. Check withgit status --ignoredon a copy of a real install.ecosystem.config.jsuses__dirname + '/backend'. Placed inapps/events/, it needs no change.adoptrewrites only installs whose copy has absolutecwdpaths.- Playwright (
apps/events/playwright.config.ts) keeps itscwd: "backend"/"frontend". Run it fromapps/events. - Docs:
ROADMAP-v3.mdandhub-protocol.mdalready live in the rootdocs/. Remove their pointer stubs fromapps/events/docs/in the merge. Code comments that citedocs/hub-protocol.mdthen point at the root copy.apps/events/docs/HANDOVER.mdkeeps the Events-only parts (where the code lives, known gaps), and the cross-product status lives in the root HANDOVER.md. CHANGELOG.mdandWHATS-NEW.mdstay inapps/events/(the Hub readsapps/events/WHATS-NEW.md). The 2.2.0 entry inWHATS-NEW.mdhas no— requires.README.mdandDEPLOYMENT.md: rewrite the deploy and install sections forcrosscode. The nginx and PM2 background stays.scripts/deploy.shandscripts/install.share removed fromapps/events. The archived repo keeps them for installs that haven't moved yet.
4. The crosscode script
It lives in this repo's root scripts/. It's bash, like today's scripts, and is checked with
shellcheck. On a server it's a checkout of main in /opt/crosscode/tools, updated with
git pull --ff-only at the start of every run, then re-run from a copy (as deploy.sh does
today, so a checkout never changes the running script).
scripts/
crosscode entry: self-update, re-run from a copy, dispatch, `help`
lib/common.sh logging, root/app-user checks, church.env read/write, tag lookup
lib/deploy.sh checks → per product in order → summary
lib/install.sh new church (from today's install.sh)
lib/adopt.sh existing Events install → monorepo
lib/status.sh
products/events.sh the product's hooks (below); accounts.sh, website.sh, app.sh follow
tests/ bats tests for the parts that don't need a server
Product hooks. Each products/<name>.sh defines backup, install_deps (npm ci --include=dev -w apps/events/backend -w apps/events/frontend), migrate, build, pm2_names,
health_url and rollback_build. With hooks, adding Accounts in phase 3 means adding a file,
not rewriting the deploy. For Events they come from today's deploy.sh: the backup through
backupUtils.runBackup(), prisma migrate deploy, the backend tsc build and next build.
church.env (/var/www/sites/<church>/church.env, mode 600, owned by root):
CHURCH=hopefamily
PRODUCTS="events" # accounts website app as they're added
ADDRESS=hopefamily.co.za # or hopefamily.crosscode.co.za
EVENTS_DIR=/var/www/sites/hopefamily/events
EVENTS_DOMAIN=events.hopefamily.co.za
EVENTS_PM2="hope-events-backend hope-events-frontend"
EVENTS_PORTS="5000 3000" # api web
EVENTS_DB=hope_events
EVENTS_USER=hopeevents
Secrets stay in each product's own .env, never in church.env.
Commands in 2.2.0:
| Command | In 2.2.0 |
|---|---|
deploy <church> [events] |
Yes. Accounts is skipped while a church has none (§8). Tags are events@x.y.z, newest by version (git tag -l 'events@*' --sort=-v:refname) |
deploy … --version events@x.y.z, --main, --check |
Yes |
deploy --every-church … |
Yes (it's a loop over /var/www/sites/*/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 |
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
heading in apps/<product>/WHATS-NEW.md. Refuse the deploy if a — requires <product> <version>
isn't met by the installed sibling or by this same run. Nothing in 2.2.0 requires anything, but
the check is built and tested now.
A deploy, per product (as deploy.sh today): refuse if files were changed by hand →
database backup → git fetch --tags and check out the tag (detached) → install and build that
app only → migrations → pm2 reload → poll /health until it reports the new version (60 s).
On failure that product goes back to its previous tag and rebuilds, and the run stops. The
summary lists each product as updated, rolled back or not reached.
5. crosscode adopt (once per existing install)
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".
- Checks: the old folder is a
hope-eventscheckout at av2.1.xtag with no files changed by hand, and/var/www/sites/<church>/eventsdoesn't exist (or is already an adopted checkout, in which case stop: nothing to do). - Read what the install already has: the PM2 names and ports from
ecosystem.config.js, and the database name frombackend/.envDATABASE_URL. Writechurch.env. - New checkout of this repo at
events@2.2.0in/var/www/sites/<church>/events, owned by the app user. - Copy the install's own files into
apps/events/:backend/.env,frontend/.env*,ecosystem.config.js(with absolutecwds rewritten),backend/data/*.json, andbackend/backups/. Thenrsync -a backend/public/uploads/, which may be large; the old site is still serving meanwhile. - Build (
npm ci -w …, backend build,next build). The old install keeps running. - Switch over (the only downtime, a few seconds): database backup → a final
rsync -a --deleteof the uploads anddata/*.json→prisma migrate statusmust show nothing pending (2.2.0 adds no migrations; refuse if it does) →pm2 deletethe two names →pm2 start ecosystem.config.jsfrom the new folder →pm2 save→/healthreports 2.2.0. - On failure at step 6:
pm2 delete→pm2 startfrom the old folder →pm2 save. Nothing in the old folder was changed, so it comes back exactly as it was. - Keep the old folder, renamed
<old>.pre-2.2.0, for 14 days.adopt --undouses it. After that,crosscode statusreminds you to remove it.
The nginx config doesn't change (it only proxies to ports), and neither do the PM2 names, the database or its name.
6. Testing
- Events, unchanged behaviour: backend Jest,
tsc --noEmit, frontend build and the Playwright e2e run, all from the monorepo. They should give the same counts as the 2.1.1 baseline. - Script:
shellcheck, plus bats tests for tag lookup, the— requiresparsing,church.envreading and writing, and the rewriting ofecosystem.config.js. - On a throwaway Ubuntu 24.04 VM (e.g. multipass), in this order:
install.shfrom the archived repo atv2.1.1. Add demo data and a few uploads.crosscode adopt→ 2.2.0 works, the uploads are there, and the database is unchanged.adopt --undo→ back on 2.1.1. Thenadoptagain.crosscode deploy <church> events --version events@2.2.0-testwith a broken migration on a test tag → it rolls back to 2.2.0 and the site stays up.- A file changed by hand →
deploy --checkrefuses it. - A second church with
crosscode installon the same VM → separate databases,.envfiles, uploads and PM2 names.deploy --every-churchupdates both. crosscode statusfor both.- The Hub (local, port 5200) sees the install's heartbeat as 2.2.0, and
events@2.2.0under Releases.
7. Rolling it out
hope-events, last commit onmain: README "Moved tocrosscode-platform/apps/events; this repo only keeps 2.1.x for installs that haven't moved". No tag.- Here: merge
move/events→npm run check→ tagevents@2.2.0→ push with tags. Remove any test tags first. - Hub: run release sync. Check that Cross Events shows 2.2.0 and the older
v…releases are still listed. - Servers: set up
/opt/crosscode/tools. Adopt a staging copy first, then each real install one at a time, checkingcrosscode statusafter each. Installs on 2.1.1 see 2.2.0 on the Hub. Their "Request update" is answered withadopt, notdeploy. - When every install reports 2.2.0: archive
hope-eventson Gitea (read-only; cloning and fetching still work, soadopt --undoand old installs keep working). - crosscode-site: nothing changes (ROADMAP §9).
- Docs: a 2.2.0 entry in
apps/events/CHANGELOG.mdand the rootCHANGELOG.md, and the root HANDOVER.md updated with 1b done and 1c (2.3.0, authenticator app 2FA) next.
Decisions
adoptbuilds next to the old install and switches over (section 5); ROADMAP §8 updated to match (decision 25).adopt --undois 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.)