From b47b1e965772031c83966504a65b8411fabe9654 Mon Sep 17 00:00:00 2001 From: Mischa Date: Sat, 4 Jul 2026 15:02:59 +0200 Subject: [PATCH] docs: add Grav 2.0.4 upgrade implementation plan 6 tasks: Phase 0 edits, local build+validate, Makefile remote targets (fix broken remote-upgrade-grav; add update/git-sync-toggle/content-status), server-install cleanup, test-env upgrade sequence, docs+prod runbook. Co-Authored-By: Claude Opus 4.8 --- .../plans/2026-07-04-grav-2.0.4-upgrade.md | 520 ++++++++++++++++++ 1 file changed, 520 insertions(+) create mode 100644 docs/working/plans/2026-07-04-grav-2.0.4-upgrade.md diff --git a/docs/working/plans/2026-07-04-grav-2.0.4-upgrade.md b/docs/working/plans/2026-07-04-grav-2.0.4-upgrade.md new file mode 100644 index 0000000..91aa199 --- /dev/null +++ b/docs/working/plans/2026-07-04-grav-2.0.4-upgrade.md @@ -0,0 +1,520 @@ +# Grav 2.0.4 Upgrade + GPM-Manage Plugins — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Status:** 📋 Not started + +**Goal:** Upgrade Grav core `2.0.0-rc.10` → `2.0.4` stable and promote `admin2`/`api`/`flex-objects` to GPM management, validated on local then the remote test env (prod is documented-only). + +**Architecture:** One dependency-forced atomic upgrade. Local core is baked into the Docker image (rebuild); the server upgrades in place via `bin/gpm self-upgrade` + `bin/gpm update`. The GPM release channel is switched from `testing` to `stable` in `user/config/system.yaml`. `git-sync` is disabled for the duration of the remote upgrade and left off pending user validation. + +**Tech Stack:** Grav 2.0 (PHP 8.3), GPM CLI, Docker Compose, Make (env-suffixed remote targets), Gitea content sync. + +**Spec:** `docs/working/specs/2026-07-04-grav-2.0.4-upgrade-design.md` + +## Global Constraints + +- Version floors (GPM enforces): `grav >= 2.0.4`, `api >= 1.0.6`, `admin2 >= 2.0.9`, `flex-objects >= 1.4.3`, `login >= 3.8.11`, `form >= 6.0.0`. Assert with `>=`, not `==` — GPM may serve a newer stable patch at execution time. +- Only write inside `travel-blog-intotheeast/` or its subfolders. +- **Dual git repos.** The project root is one repo; `user/` is a *separate* repo where only `pages/ config/ accounts/ themes/` are tracked (`plugins/` is gitignored except `cache-on-save/` and `story-blocks/`). Changes to `user/config/system.yaml` commit to the **user repo** and reach the server via `make content-push` → server pull; everything else commits to the **root repo**. +- GPM channel authority is `user/config/system.yaml` → `gpm.releases` (must be `stable` on the server *before* any GPM op). `GRAV_CHANNEL` in docker-compose is cosmetic/consistency only. +- Never read `.env*`. Use `make remote-*` targets for all server ops. +- Do not touch `twig.cache` (stays `false` in dev per CLAUDE.md). +- `git-sync` is remote-only: never add it to `plugins.txt`; disable it during the remote upgrade and leave it disabled until the user re-enables. +- Prod is empty → **Phase 3 is documentation only, never executed.** +- Verified CLI names (against the rc.10 container): `php bin/gpm self-upgrade -y` (core), `php bin/gpm update -y` (all plugins), `php bin/grav cache` (clear cache). `bin/grav upgrade` does **not** exist. + +--- + +## File structure + +| File | Repo | Responsibility | +|---|---|---| +| `Dockerfile` | root | Baked local core version (grav-admin zip URL) | +| `plugins.txt` | root | GPM plugin manifest — gains admin2/api/flex-objects | +| `docker-compose.yml` | root | `GRAV_CHANNEL` cosmetic bump | +| `user/config/system.yaml` | **user** | Authoritative GPM channel (`gpm.releases`) | +| `scripts/server-install.sh` | root | Fresh-install script — drop admin2/api special-casing | +| `scripts/git-sync-toggle.sh` | root | New: idempotently set git-sync `enabled:` on the server | +| `Makefile` | root | Fix `remote-upgrade-grav`; add 3 remote targets | +| `docs/working/plans/...` `CLAUDE.md` `docs/reference/architecture.md` | root | Runbook + stack docs | + +--- + +## Task 1: Phase 0 — core, plugin-list, and channel edits + +**Files:** +- Modify: `Dockerfile` (the grav-admin zip URL line) +- Modify: `plugins.txt` +- Modify: `docker-compose.yml` (`GRAV_CHANNEL`) +- Modify: `user/config/system.yaml` (`gpm.releases`) + +**Interfaces:** +- Produces: local image that installs Grav 2.0.4; `plugins.txt` containing `api`, `admin2`, `flex-objects`; `stable` GPM channel consumed by Task 2 (local) and Task 5 (server). + +- [ ] **Step 1: Bump the core version in the Dockerfile** + +In `Dockerfile`, change the download URL: + +```dockerfile +RUN curl -sL 'https://github.com/getgrav/grav/releases/download/2.0.4/grav-admin-v2.0.4.zip' \ + -o /tmp/grav-admin.zip \ +``` + +(Only the URL changes — the zip still extracts to `/tmp/grav-admin/`, so every `cp` line below it is unchanged.) + +- [ ] **Step 2: Add the three plugins to `plugins.txt`** + +Append these lines to `plugins.txt` (order is not significant; GPM resolves deps): + +``` +api +admin2 +flex-objects +``` + +- [ ] **Step 3: Switch the GPM channel to stable** + +In `user/config/system.yaml`, under the `gpm:` block (currently line ~212): + +```yaml +gpm: + releases: stable + official_gpm_only: true +``` + +(Change `testing` → `stable`. Leave `official_gpm_only` as-is.) + +- [ ] **Step 4: Bump the cosmetic channel env** + +In `docker-compose.yml`, under the `grav` service environment: + +```yaml + - GRAV_CHANNEL=production +``` + +- [ ] **Step 5: Commit the user-repo change** + +```bash +cd user +git add config/system.yaml +git commit -m "config: switch GPM release channel testing -> stable" +cd .. +``` + +Expected: commit succeeds in the `user` repo. + +- [ ] **Step 6: Commit the root-repo changes** + +```bash +git add Dockerfile plugins.txt docker-compose.yml +git commit -m "build: pin Grav core 2.0.4 and add admin2/api/flex-objects to plugins.txt" +``` + +Expected: commit succeeds on branch `grav-2.0.4-upgrade`. + +--- + +## Task 2: Phase 1 — local build, clean install, validation + +**Files:** +- No file edits. Executes the Task 1 changes locally. + +**Interfaces:** +- Consumes: Task 1 (Dockerfile 2.0.4, plugins.txt, stable channel). +- Produces: a proven-working local 2.0.4 stack — the go/no-go gate for the remote phases. + +- [ ] **Step 1: Remove the stale manually-extracted plugin folders** + +These were hand-extracted from the rc.10 bundle; GPM must install them fresh. + +```bash +rm -rf user/plugins/admin2 user/plugins/api user/plugins/flex-objects +``` + +Expected: the three folders are gone (`ls user/plugins/` no longer lists them). They are gitignored, so `git status` in `user/` is unaffected. + +- [ ] **Step 2: Rebuild the image with core 2.0.4** + +```bash +make build +``` + +Expected: build completes; the RUN layer downloads `grav-admin-v2.0.4.zip`. + +- [ ] **Step 3: Recreate the container** + +```bash +make start +``` + +Expected: `intotheeast_grav` is up on http://localhost:8081. + +- [ ] **Step 4: Confirm the core version is 2.0.4** + +```bash +docker exec intotheeast_grav php bin/grav --version +``` + +Expected output contains: `Grav CLI Application 2.0.4` (or a newer 2.0.x). + +- [ ] **Step 5: Update already-installed GPM plugins to stable** + +This bumps `login` (3.8.9 → ≥3.8.11, required by `api`) and `form` before the new plugins install. `gpm install` alone would skip them because they already exist. + +```bash +docker exec -w /var/www/html intotheeast_grav php bin/gpm update -y +``` + +Expected: `login`, `form`, `shortcode-core`, etc. report as updated (or already up to date). + +- [ ] **Step 6: Install the newly-listed plugins** + +```bash +make install-plugins +``` + +Expected: `admin2`, `api`, `flex-objects` install; their dependencies resolve against the now-current `login`/`form`; no "requires grav >= 2.0.4" errors. + +- [ ] **Step 7: Clear the cache** + +```bash +docker exec intotheeast_grav php bin/grav cache +``` + +Expected: "Cache cleared" output. + +- [ ] **Step 8: Assert plugin versions meet the floors** + +```bash +docker exec intotheeast_grav sh -c 'cd /var/www/html && for p in admin2 api flex-objects login form; do printf "%s: " "$p"; grep -m1 "^version:" user/plugins/$p/blueprints.yaml; done' +``` + +Expected (at least): `admin2: 2.0.9`, `api: 1.0.6`, `flex-objects: 1.4.3`, `login: 3.8.11`, `form: 9.1.8` — equal or higher. + +- [ ] **Step 9: Run the automated smoke suite** + +This exercises the posting pipeline (`test-post` submits via the real form → add-page-by-form → cache-on-save) and renders pages via Playwright — the exact admin2/api-critical path. + +```bash +make test +``` + +Expected: `test-config`, `test-post`, and `test-ui` all pass. + +- [ ] **Step 10: Manual browser spot-check** + +Visit and confirm each renders without error: +- http://localhost:8081/ (home) +- the active trip page (`/trips/japan-korea-2026`) — filter bar + map load +- one story page — hero + shortcodes render +- http://localhost:8081/admin2 — login page loads; log in +- http://localhost:8081/gpx-manager — list loads; upload a small `.gpx`, then delete it + +Expected: all load; no PHP errors in `docker logs intotheeast_grav`. + +- [ ] **Step 11: Checkpoint (no commit needed)** + +No files changed in this task. If any step failed, stop and diagnose before proceeding — this is the go/no-go gate for remote work. + +--- + +## Task 3: Remote Makefile targets (fix + additions) + +**Files:** +- Create: `scripts/git-sync-toggle.sh` +- Modify: `Makefile` (fix `remote-upgrade-grav`; add `remote-update-plugins`, `remote-git-sync-disable`, `remote-git-sync-enable`; register the new targets in `REMOTE_TARGETS`) + +**Interfaces:** +- Produces: `make remote-upgrade-grav-`, `make remote-update-plugins-`, `make remote-git-sync-disable-`, `make remote-git-sync-enable-` — consumed by Task 5. + +- [ ] **Step 1: Create the git-sync toggle script** + +Create `scripts/git-sync-toggle.sh` (piped to the server via `bash -s`, matching the `server-install.sh` pattern). It only ever rewrites the top-level `enabled:` key — never `folders` or the encrypted token. + +```bash +#!/bin/bash +set -e + +FILE="$1" +STATE="$2" +: "${FILE:?usage: git-sync-toggle.sh }" +: "${STATE:?usage: git-sync-toggle.sh }" + +if [ ! -f "$FILE" ]; then + echo "ERROR: $FILE not found — is git-sync installed on this server?" >&2 + exit 1 +fi + +if grep -qE '^enabled:' "$FILE"; then + sed -i -E "s/^enabled:.*/enabled: ${STATE}/" "$FILE" +else + printf 'enabled: %s\n' "$STATE" | cat - "$FILE" > "$FILE.tmp" && mv "$FILE.tmp" "$FILE" +fi + +echo "git-sync now: $(grep -E '^enabled:' "$FILE")" +``` + +- [ ] **Step 2: Make it executable** + +```bash +chmod +x scripts/git-sync-toggle.sh +``` + +- [ ] **Step 3: Fix the broken `remote-upgrade-grav` target** + +In `Makefile`, replace the body of `remote-upgrade-grav` (currently `php bin/grav upgrade`, which is not a real command): + +```make +remote-upgrade-grav: guard-env + $(SSH) "cd $(WEBROOT) && php bin/gpm self-upgrade -y && php bin/grav cache" +``` + +- [ ] **Step 4: Add the plugin-update target** + +Add below `remote-install-plugins`: + +```make +remote-update-plugins: guard-env + $(SSH) "cd $(WEBROOT) && php bin/gpm update -y && php bin/grav cache" +``` + +- [ ] **Step 5: Add the git-sync toggle targets** + +```make +remote-git-sync-disable: guard-env + $(SSH) "bash -s -- '$(WEBROOT)/user/config/plugins/git-sync.yaml' false" < scripts/git-sync-toggle.sh + +remote-git-sync-enable: guard-env + $(SSH) "bash -s -- '$(WEBROOT)/user/config/plugins/git-sync.yaml' true" < scripts/git-sync-toggle.sh +``` + +- [ ] **Step 6: Add a server content-status target** + +For reviewing config drift after the plugin upgrade without raw SSH: + +```make +remote-content-status: guard-env + $(SSH) "cd $(WEBROOT)/user && git status --short && echo '--- config diff ---' && git diff -- config/" +``` + +- [ ] **Step 7: Register the new targets for env-suffix generation** + +In `Makefile`, extend the `REMOTE_TARGETS` list so the `-test`/`-prod` variants get generated: + +```make +REMOTE_TARGETS := remote-env-setup remote-env-remove remote-wipe remote-install \ + remote-fetch remote-fetch-content remote-install-plugins remote-update-plugins \ + remote-upgrade-grav remote-git-sync-disable remote-git-sync-enable \ + remote-content-status remote-clean remote-maintenance-on remote-maintenance-off +``` + +- [ ] **Step 8: Verify the targets exist and expand correctly (dry run)** + +```bash +make -n remote-update-plugins-test +make -n remote-git-sync-disable-test +make -n remote-upgrade-grav-test +make -n remote-content-status-test +``` + +Expected: each prints the intended `ssh ...` command with `ENV=test` resolved, and no "No rule to make target" error. (No server is contacted by `-n`.) + +- [ ] **Step 9: Commit** + +```bash +git add scripts/git-sync-toggle.sh Makefile +git commit -m "build: fix remote-upgrade-grav; add remote plugin-update, git-sync toggle, content-status targets" +``` + +--- + +## Task 4: Fresh-install script cleanup (option B server-side) + +**Files:** +- Modify: `scripts/server-install.sh` (remove admin2/api stash+restore) + +**Interfaces:** +- Consumes: `plugins.txt` now containing admin2/api/flex-objects (Task 1). +- Produces: a fresh-install path where admin2/api/flex install purely via `gpm install $PLUGINS`. + +- [ ] **Step 1: Remove the zip-stash lines** + +In `scripts/server-install.sh`, delete lines 25–26 (the admin2/api stash into `/tmp`): + +```bash +cp -rf grav-admin/user/plugins/admin2 /tmp/admin2-plugin +cp -rf grav-admin/user/plugins/api /tmp/api-plugin +``` + +- [ ] **Step 2: Remove the restore lines** + +Delete lines 43–45 (the restore after the user re-clone): + +```bash +cp -rf /tmp/admin2-plugin user/plugins/admin2 +cp -rf /tmp/api-plugin user/plugins/api +rm -rf /tmp/admin2-plugin /tmp/api-plugin +``` + +Leave `mkdir -p user/plugins user/accounts user/data` in place. admin2/api/flex now come from `php bin/gpm install $PLUGINS -y` (unchanged line ~48). + +- [ ] **Step 3: Syntax-check the script** + +```bash +bash -n scripts/server-install.sh +``` + +Expected: no output (valid syntax). + +- [ ] **Step 4: Commit** + +```bash +git add scripts/server-install.sh +git commit -m "build: drop admin2/api zip-stash from server-install; install via GPM (option B)" +``` + +--- + +## Task 5: Phase 2 — test env upgrade + +**Files:** +- No file edits. Executes against the test environment using Task 3 targets. + +**Interfaces:** +- Consumes: Tasks 1–4 (pushed to Gitea), the `-test` make targets. +- Produces: test env on 2.0.4 with GPM-managed plugins, validated; git-sync left disabled. + +- [ ] **Step 1: Push all changes to Gitea** + +The server pulls `user/` content (incl. the stable-channel `system.yaml`) from Gitea; the root repo pushes normally. + +```bash +git push origin grav-2.0.4-upgrade # or merge to the branch the server tracks, per your deploy convention +make content-push # pushes the user repo commit (system.yaml) to Gitea +``` + +Expected: both remotes updated. (Confirm with the user which branch the test server tracks before pushing.) + +- [ ] **Step 2: Disable git-sync on test** + +```bash +make remote-git-sync-disable-test +``` + +Expected: prints `git-sync now: enabled: false`. + +- [ ] **Step 3: Pull latest content to the test server** + +Brings the `gpm.releases: stable` change onto the server *before* any GPM op. + +```bash +make remote-fetch-content-test +``` + +Expected: server `user/` fast-forwards; `user/config/system.yaml` shows `releases: stable`. + +- [ ] **Step 4: Upgrade the core on test** + +```bash +make remote-upgrade-grav-test +``` + +Expected: `bin/gpm self-upgrade` moves core rc.10 → 2.0.4 (stable channel); cache cleared. If it fails on a shared-folder error (see spec Risks), retry is safe — `self-upgrade` supports `-o/--overwrite`; add it to the target temporarily if a retry is needed. + +- [ ] **Step 5: Update all plugins on test** + +```bash +make remote-update-plugins-test +``` + +Expected: admin2 → ≥2.0.9, api → ≥1.0.6, flex-objects → ≥1.4.3, login → ≥3.8.11, form, git-sync all update to their stable versions; cache cleared. + +- [ ] **Step 6: Review server config drift** + +Inspect the server `user/` working tree for unexpected rewrites from the plugin upgrades (do NOT blind-commit): + +```bash +make remote-content-status-test +``` + +Expected: review any `config/` diffs deliberately. Discard server-specific/reformatting churn; keep only intended changes. (git-sync is disabled, so nothing auto-commits while you review.) + +- [ ] **Step 7: Smoke-test the test URL** + +Against the test site (URL per your test env), confirm: +- home, a trip page, a story render +- admin2 login works +- submit one `/post` → the entry appears in the active trip's dailies +- `/gpx-manager` lists, uploads, and deletes a file + +Expected: all pass. (git-sync stays disabled, so the new post will not auto-sync yet — that's expected and verified in Step 9.) + +- [ ] **Step 8: Notify the user — validation checkpoint** + +Report results and explicitly state that **git-sync remains disabled** on test pending their validation. Do not re-enable automatically. + +- [ ] **Step 9: (User-gated) Re-enable git-sync and verify sync** + +After the user confirms validation: + +```bash +make remote-git-sync-enable-test +make content-push # or trigger a content change; confirm it syncs through +``` + +Expected: `git-sync now: enabled: true`; a content round-trip syncs between the test server and Gitea. + +--- + +## Task 6: Docs, prod runbook, and memory + +**Files:** +- Modify: `CLAUDE.md` (stack versions + plugin-management model) +- Modify: `docs/reference/architecture.md` (versions/channel) +- Modify: `docs/working/plans/2026-07-04-grav-2.0.4-upgrade.md` (this file — Phase 3 runbook + Status) +- Modify: memory files under the auto-memory dir (project-grav2-upgrade, project-plugin-architecture) + +**Interfaces:** +- Consumes: the completed local + test upgrade. +- Produces: current docs; an executable-but-unexecuted prod runbook. + +- [ ] **Step 1: Update the stack facts in `CLAUDE.md`** + +Change the "Current stack" block: Grav `2.0.4` (not rc.10); Admin2 to the installed stable version; note that admin2/api/flex-objects are now **GPM-managed via `plugins.txt`** (no longer hand-extracted); note `gpm.releases: stable`. + +- [ ] **Step 2: Update `docs/reference/architecture.md`** + +Reflect core 2.0.4, stable channel, and the three-category plugin model (GPM-managed / former-manual-now-GPM / remote-only git-sync). + +- [ ] **Step 3: Write the Phase 3 prod runbook** + +Append a "Phase 3 — Production (fresh install, NOT executed)" section to this plan documenting: run `make remote-install-prod` with `GRAV_VERSION=2.0.4`; admin2/api/flex install via GPM from `plugins.txt`; then set up git-sync manually (install, add encrypted token, apply the `folders:` array fix per `docs/working/git-sync-notes.md`), and leave it disabled until first validation. + +- [ ] **Step 4: Update memory** + +Update `project-grav2-upgrade.md` (now on 2.0.4 stable; GPM serves stable so direct-download-only no longer applies) and `project-plugin-architecture.md` (admin2/api/flex now GPM-managed; git-sync remote-only category). Refresh the `MEMORY.md` pointers if the hooks change. + +- [ ] **Step 5: Set the plan Status to complete** + +Change the `**Status:**` line at the top of this file to `✅ Complete (YYYY-MM-DD)` (today's date at execution). + +- [ ] **Step 6: Commit** + +```bash +git add CLAUDE.md docs/reference/architecture.md docs/working/plans/2026-07-04-grav-2.0.4-upgrade.md +git commit -m "docs: record Grav 2.0.4 upgrade; GPM-managed plugins; prod runbook" +``` + +(Memory files live outside the repo; they are written directly, not committed here.) + +--- + +## Rollback + +If any phase fails and cannot be fixed forward: +1. `git revert` the relevant commits on `grav-2.0.4-upgrade` (root repo) and the `user` repo `system.yaml` commit. +2. Local: `make build && make start && make install-plugins`. +3. Test server: revert is delivered via `make content-push` + `make remote-fetch-content-test`; if core was already self-upgraded, reinstall the rc.10 core via the fresh-install path or `bin/gpm self-upgrade` cannot downgrade — treat a completed core upgrade as forward-only and fix forward instead. + +Content, config, and accounts are in git, so no data restore is required.