docs: capture local Grav core upgrade + refresh version-authority docs
New learning: docs/solutions/tooling-decisions/upgrade-local-grav-core-rebuild-docker-image.md — the local Grav core is baked into the Docker image (only ./user is bind-mounted), so it upgrades by a Dockerfile URL bump + image rebuild + `docker rm -f` recreate, not the `gpm self-upgrade` the servers use (non-durable in-container). Refreshed three docs this exposed as stale/incomplete: - local-setup.md: rewrote the stale "newer Grav RC" section with the durable rebuild procedure (recreate gotcha, verify, plugin refresh, non-durability note). - deploy-cycle.md: Phase 0 now upgrades the local core; state-model notes the image as a fourth surface beyond the three server layers. - stale-grav-version-blocks-api-plugin-install.md: version-authority surfaces 3 -> 4 (hardcoded Dockerfile URL); clarified .env* GRAV_VERSION governs fresh remote installs only, never the local Docker core. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Np4cMQLF77i664CAQXySzU
This commit is contained in:
Claude Opus 4.8
@@ -34,6 +34,11 @@ Referenced gotcha docs:
|
||||
- `docs/solutions/architecture-patterns/git-sync-secret-exposure-and-tracked-file-boomerang.md` — gitignore is the sync boundary; env-tree leak.
|
||||
- `docs/solutions/conventions/grav-plugin-config-must-be-tracked-override.md` — plugin config must live in the tracked override.
|
||||
|
||||
These three layers describe the **servers**. Locally there is a fourth: the Grav
|
||||
**core** is baked into the Docker **image** (`Dockerfile`), not in any layer above —
|
||||
so the local core upgrades by an image rebuild, never by the `gpm self-upgrade` the
|
||||
servers use. See `docs/solutions/tooling-decisions/upgrade-local-grav-core-rebuild-docker-image.md`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Local (author + prove the change)
|
||||
@@ -42,7 +47,8 @@ Referenced gotcha docs:
|
||||
- GPM channel: `gpm.releases: stable` in `user/config/system.yaml` (authoritative; reaches servers via content pull, so it must be right **before** any server GPM op).
|
||||
- `plugins.txt` — the GPM-managed set only. **Never** add `git-sync` (it is remote-only).
|
||||
- Prod-only overrides (Twig cache/debug, `debugger.shutdown.close_connection: false`) in `deploy/env/prod/system.yaml` — **never** commit prod values into `user/config/system.yaml`.
|
||||
- **Bump `GRAV_VERSION` in `.env.test` and `.env.prod`** to the target version. A stale value here installs the wrong core (an rc), which then blocks the `api` plugin and 404s admin.
|
||||
- **Bump `GRAV_VERSION` in `.env.test` and `.env.prod`** to the target version. A stale value here installs the wrong core (an rc), which then blocks the `api` plugin and 404s admin. This governs fresh **remote** installs only.
|
||||
- **If the core version is changing, upgrade the local dev core too** so you prove the change against the target version — bump the hardcoded `grav-admin-v<ver>.zip` URL in `Dockerfile`, `docker compose build grav`, then `docker rm -f intotheeast_grav && docker compose up -d grav`. The local core is baked into the image, so `.env GRAV_VERSION` does *not* touch it and an in-container `gpm self-upgrade` is non-durable. See `docs/solutions/tooling-decisions/upgrade-local-grav-core-rebuild-docker-image.md`.
|
||||
2. `make build-assets` if you touched `js/src/*` (never hand-edit the bundled `js/*.js`).
|
||||
3. Run the dev server (`docker compose … up`) and the Playwright suite.
|
||||
4. Pre-flight assertions:
|
||||
|
||||
@@ -44,13 +44,34 @@ This creates uid 1000 in the container, chowns `/var/www/html` to 1000:1000, and
|
||||
|
||||
---
|
||||
|
||||
## Upgrading to a newer Grav RC
|
||||
## Upgrading the Grav core
|
||||
|
||||
Grav 2.0 is baked into the custom Docker image via `Dockerfile`. The base `getgrav/grav` image ships 1.7 — the `Dockerfile` downloads the 2.0 RC bundle from GitHub and overwrites the core files at build time.
|
||||
The Grav core is baked into the custom Docker image via `Dockerfile`. The base
|
||||
`getgrav/grav` image ships 1.7 — the `Dockerfile` downloads the pinned stable bundle
|
||||
(`grav-admin-v<version>.zip`) from GitHub and overwrites the core files at build time.
|
||||
`docker-compose.yml` volume-mounts only `./user`, so the core lives in the **image
|
||||
layer**. That means you upgrade the core by rebuilding the image, **not** by running
|
||||
`gpm self-upgrade` inside the container — an in-container self-upgrade is lost on the
|
||||
next rebuild. (The servers are the opposite: no image, so they self-upgrade in place.)
|
||||
|
||||
To upgrade:
|
||||
1. Update the bundle URL in `Dockerfile`
|
||||
2. Run `make setup` — Docker rebuilds the image layer automatically
|
||||
1. Bump **both** occurrences of the version in the `Dockerfile` release URL (the
|
||||
`/download/<ver>/` path and the `grav-admin-v<ver>.zip` filename). Note: the
|
||||
`GRAV_VERSION` in `.env*` does **not** drive this build — it only pins fresh
|
||||
*remote* installs.
|
||||
2. Rebuild: `docker compose build grav`.
|
||||
3. Recreate the container. `docker compose up -d` won't replace an already-running
|
||||
container with a fixed `container_name` (it errors `Conflict … name … already in
|
||||
use`), so remove it first — safe because `./user` is a bind mount:
|
||||
```bash
|
||||
docker rm -f intotheeast_grav && docker compose up -d grav
|
||||
```
|
||||
4. Verify: `docker exec -w /var/www/html intotheeast_grav php bin/grav --version`.
|
||||
5. Refresh plugins and clear cache: `make install-plugins` then
|
||||
`docker exec -w /var/www/html intotheeast_grav php bin/grav cache`.
|
||||
|
||||
Full rationale and the server-vs-local contrast:
|
||||
`docs/solutions/tooling-decisions/upgrade-local-grav-core-rebuild-docker-image.md`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user