intotheeast-com/README.md

# 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`](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`](docs/reference/testing.md) |
| `php/` | Local PHP ini overrides |
| `docs/` | All project documentation — start at [`docs/README.md`](docs/README.md) |
| `docs/guides/` | Operational how-tos (posting, story authoring, 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

```bash
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:

```bash
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:**

```bash
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:

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

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

```bash
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`](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

```bash
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.