m038/intotheeast-com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: extract local setup guide from CLAUDE.md; add skill path overrides

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WPJztrVGbwic2xTG7G9fjM
This commit is contained in:
Mischa
2026-06-21 13:04:31 +02:00
parent b1efa699f0
commit 0eb6254085
2 changed files with 118 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+5 -61
View File
@@ -116,67 +116,11 @@ The custom plugin at `user/plugins/cache-on-save/` clears Grav's page-tree cache
## 2. Local development setup ## 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 Specs: `docs/working/specs/YYYY-MM-DD-<topic>-design.md`
mkdir -p user/plugins user/data Plans: `docs/working/plans/YYYY-MM-DD-<topic>.md`
```
Then run `make setup` (starts Docker + installs plugins). The brainstorming and writing-plans skills default to `docs/superpowers/`; these lines override that default.
### 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/<username>.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.
docs/guides/local-setup.md
+113
View File
@@ -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/<username>.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.