From 9beb22f4c206f45e71b97b57178ca65b1744488f Mon Sep 17 00:00:00 2001 From: Mischa Date: Thu, 18 Jun 2026 23:00:02 +0200 Subject: [PATCH] docs: add Grav 2.0 upgrade design spec Co-Authored-By: Claude Sonnet 4.6 --- .../specs/2026-06-18-grav2-upgrade-design.md | 168 ++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-18-grav2-upgrade-design.md diff --git a/docs/superpowers/specs/2026-06-18-grav2-upgrade-design.md b/docs/superpowers/specs/2026-06-18-grav2-upgrade-design.md new file mode 100644 index 0000000..5339dec --- /dev/null +++ b/docs/superpowers/specs/2026-06-18-grav2-upgrade-design.md @@ -0,0 +1,168 @@ +# Grav 2.0 Upgrade — Design Spec + +**Goal:** Upgrade the intotheeast travel blog from Grav 1.7.x to Grav 2.0 RC on a feature branch, validate full Milestone 1 functionality, and prepare a clean production fresh-install path. + +**Context:** Departure date is 2026-07-15. The production server has never been deployed, so production gets a fresh Grav 2.0 install — no in-place migration required. Local dev uses Docker; production uses PHP 8.4 directly. + +--- + +## Scope + +Two tracks: + +1. **Local dev track** — swap Docker image to Grav 2.0, validate all functionality +2. **Production track** — update `server-install.sh` and `.env` so `make remote-install` deploys Grav 2.0 fresh + +All work on branch `update-to-2.0`. + +--- + +## Compatibility Assessment + +| Component | Status | Action required | +|---|---|---| +| `form`, `login`, `email`, `error`, `problems`, `flex-objects` | ✅ First-party | Auto-updated to 2.0 versions via GPM | +| `shortcode-core` | ✅ First-party | Same | +| `cache-on-save` (custom) | ✅ Should work | Add Grav 2.0 compat flag to `blueprints.yaml`; uses `onFormProcessed` which is unchanged | +| `shortcode-gallery-plusplus` | ✅ Likely works | Plugin arch unchanged; test and confirm | +| `add-page-by-form` | ⚠️ Archived Aug 2024 | Try as-is (plugin arch unchanged, may work); if broken, write a custom replacement | +| Custom `intotheeast` theme | ✅ Should work | Twig 3 compat mode covers existing templates; test rendering | +| `linuxserver/grav` Docker image | ❌ Not supported | Replace with `getgrav/grav` + `GRAV_CHANNEL=beta` | + +--- + +## Track 1 — Local Dev + +### Changes + +**`docker-compose.yml`** + +Replace: +```yaml +image: lscr.io/linuxserver/grav:latest +environment: + - PUID=1000 + - PGID=1000 +volumes: + - ./user:/config/www/user +``` + +With: +```yaml +image: getgrav/grav +environment: + - GRAV_CHANNEL=beta +volumes: + - ./user:/var/www/html/user +``` + +**`Makefile`** — three targets reference the linuxserver internal path `/app/www/public`; replace with `/var/www/html`: +- `install-plugins`: `docker exec -w /app/www/public` → `docker exec -w /var/www/html` +- `demo-load` clear cache: `/app/www/public` → `/var/www/html` +- `demo-reset` clear cache: same + +**`user/plugins/cache-on-save/blueprints.yaml`** (create — does not exist yet) — minimal blueprint with Grav 2.0 compat flag: +```yaml +name: Cache On Save +version: 1.0.0 +description: Clears Grav cache on new-entry form submission +author: + name: Mischa +license: MIT + +dependencies: + - { name: grav, version: '>=1.6.0' } + +grav: + version: ['1.7', '2.0'] +``` + +**`user/config/system.yaml`** — switch GPM to testing channel so `make setup` resolves 2.0-compatible plugin versions: +```yaml +gpm: + releases: testing +``` + +### Validation Checklist (smoke test after `make setup`) + +Run in order — stop and investigate if any step fails: + +1. **Site loads** — `http://localhost:8081` returns the tracker page (200, no PHP errors) +2. **Admin2 loads** — `/admin` renders the new SPA admin (not the old Twig admin) +3. **Login works** — log in via Admin2 with existing credentials +4. **Posting form** — submit `/post` form with title + text; entry appears immediately in `/tracker` +5. **Photo upload** — submit `/post` form with a photo; image renders in the entry +6. **Gallery** — visit an entry with multiple photos; `shortcode-gallery-plusplus` renders gallery with lightbox +7. **Cache invalidation** — submit a second post; it appears without a manual cache clear (validates `cache-on-save`) +8. **Theme rendering** — check tracker, entry, map, post-form, and stats templates for layout/CSS regressions +9. **Playwright suite** — `make test-ui` passes all 25 tests. If any tests fail, investigate whether the failure is a genuine regression (blocker) or a test that needs updating for Admin2's new DOM structure (acceptable — update the test) + +### If `add-page-by-form` fails + +If step 4 fails due to `add-page-by-form` incompatibility, the fallback is to write a custom replacement plugin. The existing `cache-on-save` plugin is a good template — it hooks `onFormProcessed` and that API is unchanged. The replacement would use the same hook to: +1. Build the page path and slug from form fields +2. Create the page file on disk (same logic `add-page-by-form` does in PHP) +3. Clear cache (merging `cache-on-save` functionality) + +This is ~1 day of work and should be planned as a follow-up task if needed. + +--- + +## Track 2 — Production (Fresh Install) + +Production has PHP 8.4 (compatible with Grav 2.0's PHP 8.3+ requirement) and has never been deployed. + +### Changes + +**`server-install.sh`** — the download URL for Grav 2.0 RC requires a `?testing` query parameter: + +Current: +```bash +wget --no-verbose "https://getgrav.org/download/core/grav-admin/$GRAV_VERSION" -O grav-admin.zip +``` + +Updated (conditionally append `?testing` for pre-release versions, or accept a full URL suffix via env var): +```bash +wget --no-verbose "https://getgrav.org/download/core/grav-admin/${GRAV_VERSION}${GRAV_CHANNEL_SUFFIX}" -O grav-admin.zip +``` + +Where `GRAV_CHANNEL_SUFFIX` is `?testing` for RC versions and empty for stable. + +**`.env`** (not committed — edit on the server directly or locally before `make remote-install`) — update: +``` +GRAV_VERSION=2.0.0-rc.9 +GRAV_CHANNEL_SUFFIX=?testing +``` + +When Grav 2.0 goes stable, remove `GRAV_CHANNEL_SUFFIX` and update `GRAV_VERSION` to the stable version number. + +**`user/config/system.yaml`** — keep `gpm.releases: testing` (already set in Track 1) so production also installs 2.0-compatible plugin versions. + +### Production deploy + +When local validation passes: +```bash +make remote-install +``` + +That's it — fresh Grav 2.0 install from scratch with all plugins, content from Gitea, and the existing `user/` config. + +--- + +## Out of Scope + +- MCP server setup (`grav-mcp` Node.js binary) — a separate task after Grav 2.0 is stable on production +- Admin2 theming or customization +- Grav 2.0 REST API integration +- Switching `add-page-by-form` to the API-based approach (only if the plugin breaks) + +--- + +## Go/No-Go Criteria + +Ship to production before departure (2026-07-15) **only if**: +- All 9 smoke test steps pass +- Playwright suite passes +- `add-page-by-form` posting workflow works end-to-end (or a custom replacement is in place and tested) + +If any of these fail and cannot be resolved with time to spare before departure, stay on Grav 1.7 for the trip and revisit post-trip.