m038
1ae383cf5d
Adds section 1 to CLAUDE.md covering the current development mode config (twig.cache: false), the production mode values to restore at launch, and an explicit rule never to flip modes mid-development to work around bugs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
92 lines
3.8 KiB
Markdown
92 lines
3.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
## 0. Project specifics
|
|
|
|
**Only ever write changes in this folder (travel-blog-intotheeast/) or its subfolders.**
|
|
|
|
### Folder explanation
|
|
|
|
- **./**: Grav CMS dev environment for intotheeast travel blog
|
|
- **scripts/**: Server install and maintenance scripts
|
|
- **user/**: Site content, config, pages, and theme (standalone git repo — do not modify from here)
|
|
|
|
### Environment
|
|
|
|
**Never read `.env`** — it contains sensitive credentials. You may pass it to commands (e.g. `docker compose`, `make`) but never read its contents directly. Ask the user if you need environment-specific information.
|
|
|
|
### Remote operations
|
|
|
|
Always use `make` commands for anything on the production server (`make remote-install-plugins`, `make remote-clean`, etc.) — never SSH directly since credentials live in `.env`. If a remote operation isn't covered by an existing `make` command, either ask the user to run it manually or suggest adding a new `make` command if it seems reusable.
|
|
|
|
### Content sync
|
|
|
|
- `make content-push` — commit and push `user/` to Gitea (triggers production pull via webhook)
|
|
- `make content-pull` — pull latest from Gitea to local
|
|
- `plugins.txt` is manually maintained — installing a plugin via Admin does NOT update it
|
|
|
|
### User repo gitignore
|
|
|
|
Only these folders are tracked in the `user/` Git repo: `pages/`, `config/`, `accounts/`, `themes/`. The `plugins/` and `data/` folders are excluded.
|
|
|
|
## 1. Environment modes
|
|
|
|
### Rule: do not switch modes during development
|
|
|
|
**Never toggle between development and production mode mid-session.** If a caching or config issue appears, fix it at the application level (plugin, template logic) rather than temporarily flipping a mode flag to work around it. Mode switches introduce inconsistent state and make bugs harder to reproduce.
|
|
|
|
### Development mode (current)
|
|
|
|
Active settings in `user/config/system.yaml`:
|
|
|
|
| Setting | Dev value | Why |
|
|
|---|---|---|
|
|
| `twig.cache` | `false` | Theme file edits take effect immediately; no stale compile errors |
|
|
|
|
With these settings, Grav rebuilds templates on every request. This is intentionally slower but means you never need to flush cache after editing a `.html.twig` file.
|
|
|
|
### Production mode (not yet configured)
|
|
|
|
Before going live, change in `user/config/system.yaml`:
|
|
|
|
| Setting | Prod value | Why |
|
|
|---|---|---|
|
|
| `twig.cache` | `true` | Templates compiled once and reused; safe because theme files don't change at runtime |
|
|
|
|
**Pre-launch smoke test required:** with `twig.cache: true`, submit one post via `/post` and confirm the entry appears in `/tracker` immediately. This verifies the cache-on-save plugin (BUG-001 fix) works correctly with caching enabled.
|
|
|
|
### What the cache-on-save plugin handles
|
|
|
|
The custom plugin at `user/plugins/cache-on-save/` clears Grav's page-tree cache on every `new-entry` form submission. This ensures new posts appear in the tracker feed immediately in both modes — it does not depend on whether Twig caching is on or off.
|
|
|
|
## 2. Local development setup
|
|
|
|
### First-time setup after cloning
|
|
|
|
`user/plugins/` and `user/data/` are excluded from git but Grav requires them to exist. Create them once after cloning:
|
|
|
|
```bash
|
|
mkdir -p user/plugins user/data
|
|
```
|
|
|
|
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, the cache/logs/tmp directories may have wrong ownership (gpm runs as root inside the container). Fix with:
|
|
|
|
```bash
|
|
docker exec intotheeast_grav chown -R abc:users /app/www/public/cache /app/www/public/logs /app/www/public/tmp
|
|
```
|
|
|
|
### 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.
|