into the east — Grav CMS

Grav CMS travel blog. Local dev via Docker; production on a VPS managed entirely through make.

---

Repository structure

Two git repos:

Repo	Contents	Location
intotheeast.com (this repo)	Docker setup, Makefile, scripts, tests, docs, plugins.txt	./
intotheeast.com-content	Site config, pages, theme	user/ (git submodule)

user/ is tracked by this repo as a git submodule — it has its own Gitea remote and its own push/pull cadence (make content-push / make content-pull), and this repo pins an exact user/ commit. The Git Sync plugin on the server pulls from Gitea automatically when content is pushed. A persistent M user / m user in git status is normal, not a problem; see docs/solutions/architecture-patterns/dual-repo-submodule-workflow.md.

Folder map

Path	Contents
user/	Site content, config, pages, theme (the content submodule)
user/themes/intotheeast/js/src/	JS sources — esbuild inputs; run make build-assets after editing. Note js/maplibre-utils.js and js/nav.js are also sources, despite sitting beside the generated bundles
deploy/env/	Per-environment Grav config overrides (e.g. prod Twig settings)
deploy/patches/	Tracked patches for third-party plugins, which are otherwise git-ignored
scripts/	Server install and maintenance scripts
tests/	Playwright suite — see docs/reference/testing.md
php/	Local PHP ini overrides
docs/	All project documentation — start at docs/README.md
docs/guides/	Operational how-tos (posting, GPX, trip switching, setup, deploy cycle)
docs/reference/	Stable facts: architecture, design system, testing
docs/solutions/	Write-ups of bugs and workflow traps already hit, with YAML frontmatter (module, tags, problem_type)
docs/working/	Specs, plans, backlog, QA — work in flight
CONCEPTS.md	Shared domain vocabulary (Trip, Entry, Story, Active Trip)
CLAUDE.md	Rules and gotchas loaded into every Claude Code session

---

Prerequisites

• Docker (for local dev)
• SSH access to the production server
• Both Gitea repos created and accessible
• A Gitea personal access token with repo read/write access

---

Local development setup

cp .env.example .env   # fill in your values — never commit this file
make setup             # start Docker container and install plugins

Site runs at http://localhost:8081.

Clone the user content repo into user/ if not already present:

git clone $USER_REPO user/

---

First-time server setup

1. Fill in .env — copy .env.example and set all values including REMOTE_USER, REMOTE_HOST, USER_REPO, MAIN_REPO, and Gitea credentials.

2. Run the install:

make remote-install

This SSHes into the server, downloads Grav, clones both repos (user content + this config repo), installs plugins, and prints the server's SSH public key.

3. Add the SSH key to Gitea — copy the printed public key and add it as a read-only deploy key to both Gitea repos. After this, make remote-fetch works without credentials.

---

Content sync workflow

To pull editor changes locally:

make content-pull   # pull latest user/ content from Gitea → local

To push local changes to Gitea (triggers server sync):

git -C user add -A && git -C user commit -m "content: describe change"
make content-push   # push local user/ commits → Gitea

---

All commands

Local

Command	Description
make setup	First run: build → start → install plugins → fix perms
make start	Start the local Docker container
make stop	Stop the local Docker container
make install-plugins	(Re)install plugins from plugins.txt, then apply local plugin patches
make apply-plugin-patches	Idempotently re-apply the patches in deploy/patches/
make fix-perms	Reset file ownership inside the container
make build-assets	Run esbuild over user/themes/intotheeast/js/src/ — required after editing any JS source
make content-push	Push local user/ commits to Gitea (triggers the production pull)
make content-pull	Pull latest user/ content from Gitea

Testing

Command	Description
make test	Everything: test-config → test-post → test-ui
make test-config	Form/config sanity checks
make test-post	End-to-end post submission
make test-ui	Playwright suite

Details and conventions: docs/reference/testing.md.

Demo content and imports

Command	Description
make demo-load	Copy every fixture trip under user/docs/demo/trips/ into the pages tree (add a fixture by dropping a folder there — no Makefile edit needed)
make demo-reset	Remove those demo trips from the pages tree and clear cache
make pixelfed-import	Import posts from Pixelfed via scripts/pixelfed-import.py

Parallel work

Command	Description
make worktree-new NAME=<feature>	Create a worktree with its own user/ checkout and an isolated dev server on port 8090+
make worktree-rm NAME=<feature>	Tear one down cleanly (compose down → submodule deinit → worktree remove → prune)

Remote credentials

Command	Description
make remote-env-setup	Write Gitea credentials to ~/.env-intotheeast on the server
make remote-env-remove	Delete ~/.env-intotheeast from the server

Always run make remote-env-remove when done. Credentials must not persist on the server.

Remote server management

Command	Description
make remote-install	First-time install: download Grav, clone both repos, install plugins
make remote-fetch	Pull latest config repo (Makefile, scripts, plugins.txt) on the server
make remote-install-plugins	Install/update plugins from local plugins.txt on the server
make remote-upgrade-grav	Upgrade Grav core on the server
make remote-clean	Clear Grav cache on the server
make remote-maintenance-on	Enable maintenance mode (visitors see offline page)
make remote-maintenance-off	Disable maintenance mode

Typical upgrade workflow

make remote-maintenance-on
make remote-upgrade-grav
make remote-install-plugins
make remote-clean
make remote-maintenance-off

---

Plugins

Plugins are not committed to git. The full list is in plugins.txt — one plugin name per line.

• Locally: make install-plugins
• On server: make remote-install-plugins

---

Template behaviour

Key design decisions that affect how pages render:

Context	Sort order	Reason
Trip page (trip.html.twig)	Ascending (oldest first)	Trip reads as a narrative from start to finish
Homepage active-trip feed (home.html.twig)	Descending (newest first)	Visitors want to see what's happening right now

Homepage modes — controlled by travelling in user/config/site.yaml:

travelling	Homepage shows
true	Active trip map + chronological feed (newest first)
false	Map with highlight markers + curated highlights grid (max 6, 1 per trip, random)

Entries and stories opt into the highlights grid via featured: true in their frontmatter. The active_trip field stores a full page route (e.g. /trips/italy-2026-demo), not a bare slug.

Per-trip map settings — configurable in Admin2 under the Trip tab:

Setting	Values	Default	Notes
use_gpx	Yes / No	Yes	Draws uploaded GPX files as route lines on the map
autoconnect	off / on / manual / intelligent_gpx	on	Controls connector lines between location markers

Connect markers behaviour:

Value	Behaviour
off	No connector lines; force_connect on entries is also ignored
on	Dashed connector between every entry in date order
manual	No automatic lines; only entries with force_connect: true are linked
intelligent_gpx	Suppresses the connector where a GPX track covers the route; force_connect overrides. Requires use_gpx enabled — falls back to on if GPX is off or no files are present

use_gpx and autoconnect are independent: you can show GPX tracks without connector lines or vice versa.

---

Security

• .env is gitignored. Never commit it — it contains your server credentials and Gitea token.
• GITEA_TOKEN exists only in .env locally, and in ~/.env-intotheeast on the server only during active sessions. Always run make remote-env-remove after use.
• ~/.env-intotheeast has chmod 600 — readable only by the SSH user.
• The server pulls from Gitea using its SSH deploy key (read-only). No long-lived token is stored on the server after initial install.
• scripts/server-install.sh writes ~/.netrc for the initial clone only, and deletes it immediately after via a trap handler — even if the script fails.
• Credentials are never passed as command-line arguments (they would appear in server process listings). They are passed as environment variables within the SSH session.