From 0eb62540854011b36243508d672cdcb569920feb Mon Sep 17 00:00:00 2001 From: Mischa Date: Sun, 21 Jun 2026 13:04:31 +0200 Subject: [PATCH] docs: extract local setup guide from CLAUDE.md; add skill path overrides Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01WPJztrVGbwic2xTG7G9fjM --- CLAUDE.md | 66 ++-------------------- docs/guides/local-setup.md | 113 +++++++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+), 61 deletions(-) create mode 100644 docs/guides/local-setup.md diff --git a/CLAUDE.md b/CLAUDE.md index 07a2cd6..498cc59 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -116,67 +116,11 @@ The custom plugin at `user/plugins/cache-on-save/` clears Grav's page-tree cache ## 2. Local development setup -### First-time setup after cloning +Full setup guide: [`docs/guides/local-setup.md`](docs/guides/local-setup.md) -`user/plugins/` and `user/data/` are excluded from git but Grav requires them to exist. Create them once after cloning: +### Superpowers skill paths -```bash -mkdir -p user/plugins user/data -``` +Specs: `docs/working/specs/YYYY-MM-DD--design.md` +Plans: `docs/working/plans/YYYY-MM-DD-.md` -Then run `make setup` (starts Docker + installs plugins). - -### After make install-plugins: fix cache permissions - -If the site returns a 500 error after plugin installation or after recreating the container, -run `make fix-perms`. This creates uid 1000 in the container, chowns `/var/www/html` to 1000:1000, -and reloads Apache. Always run `make setup` (not just `make start`) after `docker compose down && up` -to ensure permissions are correct. - -### Grav 2.0 upgrade (local) - -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.10 bundle from GitHub and overwrites the core files at build time, so the image always contains 2.0. - -`make setup` = `build → start → install-plugins → fix-perms`. After any `docker compose down`, run `make setup` to get back to a fully working state. `docker compose restart` (soft restart) also preserves the image, so Grav 2.0 stays. - -To upgrade to a newer RC: update the URL in `Dockerfile` and run `make setup` — Docker rebuilds the image layer automatically. - -After upgrading, ensure these settings in `user/config/system.yaml`: -```yaml -accounts: - type: flex # required for Admin2 API -pages: - type: flex # required for Admin2 pages API -``` - -And ensure the admin user account has `api.*` permissions (Admin2 uses a new permission namespace): -```yaml -# user/accounts/.yaml -access: - admin: - login: true - super: true - api: - super: true - access: true -``` - -**Disable the old `admin` plugin** once `admin2` is installed — both route to `/admin` and conflict: -```bash -# In user/plugins/admin/admin.yaml: -enabled: false -``` - -**JWT secret:** Leave `jwt_secret: ''` in `user/plugins/api/api.yaml` — it works for local dev and production installs generate a secure secret automatically. - -### Language URL prefix - -If Grav redirects to `/en/...` URLs, ensure `user/config/system.yaml` contains: - -```yaml -languages: - supported: [en] - include_default_lang: false -``` - -Without `include_default_lang: false`, Grav adds a language prefix to all URLs even for single-language sites. +The brainstorming and writing-plans skills default to `docs/superpowers/`; these lines override that default. diff --git a/docs/guides/local-setup.md b/docs/guides/local-setup.md new file mode 100644 index 0000000..66cac1c --- /dev/null +++ b/docs/guides/local-setup.md @@ -0,0 +1,113 @@ +# Local Development Setup + +This guide covers setting up the dev environment from scratch after cloning the repo. + +--- + +## First-time setup + +`user/plugins/` and `user/data/` are excluded from git but Grav requires them to exist. Create them once: + +```bash +mkdir -p user/plugins user/data +``` + +Then run: + +```bash +make setup +``` + +`make setup` = `build → start → install-plugins → fix-perms`. This builds the Docker image (Grav 2.0 baked in), starts the container, installs all plugins from `plugins.txt`, and fixes file ownership. + +The dev server runs at **http://localhost:8081**. + +--- + +## After any docker compose down + +Always run `make setup` — not just `make start` — to ensure permissions are correct. + +`docker compose restart` (soft restart) preserves the image and is fine for quick restarts. Only `make setup` is needed after `docker compose down`. + +--- + +## Fix 500 errors after plugin install + +If the site returns a 500 error after plugin installation or after recreating the container: + +```bash +make fix-perms +``` + +This creates uid 1000 in the container, chowns `/var/www/html` to 1000:1000, and reloads Apache. + +--- + +## Upgrading to a newer Grav RC + +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. + +To upgrade: +1. Update the bundle URL in `Dockerfile` +2. Run `make setup` — Docker rebuilds the image layer automatically + +--- + +## Required system.yaml settings (Grav 2.0) + +After upgrading, verify these are set in `user/config/system.yaml`: + +```yaml +accounts: + type: flex # required for Admin2 API +pages: + type: flex # required for Admin2 pages API +``` + +--- + +## Admin user API permissions + +The admin user account needs `api.*` permissions for Admin2. In `user/accounts/.yaml`: + +```yaml +access: + admin: + login: true + super: true + api: + super: true + access: true +``` + +--- + +## Disable the old admin plugin + +Both `admin` and `admin2` route to `/admin` and conflict. After installing `admin2`, disable the old one: + +In `user/plugins/admin/admin.yaml`: +```yaml +enabled: false +``` + +--- + +## JWT secret + +Leave `jwt_secret: ''` in `user/plugins/api/api.yaml`. It works for local dev; production installs generate a secure secret automatically during `make remote-install`. + +--- + +## Language URL prefix + +If Grav redirects to `/en/...` URLs, ensure `user/config/system.yaml` contains: + +```yaml +languages: + supported: [en] + include_default_lang: false +``` + +Without `include_default_lang: false`, Grav adds a language prefix to all URLs even for single-language sites.