# 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.