natascha-rieter-nl/docs/superpowers/plans/2026-06-13-deployment-toolchain.md

# Deployment Toolchain Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build a complete Make-based deployment toolchain for the natascha-rieter.nl Grav CMS site, covering initial server setup, content sync via Gitea, remote Grav management, temporary credential handling, and maintenance mode.

**Architecture:** Two git repos (root config repo + user content repo) are cloned on both local machine and server. The Makefile is the single interface for all operations, building SSH commands from local `.env`. Gitea credentials exist on the server only when explicitly written by `remote-env-setup` and are always removed with `remote-env-remove`. Content sync goes through Gitea; the Grav Sync plugin handles automatic server-side pulls. The `user/` directory is a standalone nested git repo (replacing git subtree).

**Tech Stack:** GNU Make, Bash (scripts only where Make is insufficient), SSH, Grav CMS 1.7, Gitea, Git, Docker (local only)

---

## File Map

| Action | File |
|--------|------|
| Modify | `.env.example` |
| Modify | `Makefile` |
| Modify | `scripts/server-install.sh` |
| Create | `scripts/server-maintenance.sh` |
| Modify | `README.md` |

---

### Task 1: Update `.env.example`

Add `USER_REPO`, `MAIN_REPO`, `SITE_CONFIG_DIR`. Rename `REPO` → `USER_REPO`. Add comments.

**Files:**
- Modify: `.env.example`

- [ ] **Step 1: Replace `.env.example` content**

```
# SSH connection
REMOTE_USER=root
REMOTE_HOST=example.com
REMOTE_HOME=/home/example.com

# Server paths (derived from REMOTE_HOME in Makefile; override here if needed)
WEBROOT=/home/example.com/public_html
SITE_CONFIG_DIR=/home/example.com/site-config

# Grav
GRAV_VERSION=1.7.49.5

# Repos
USER_REPO=https://gitea.example.com/org/natascha-rieter.nl-user.git
MAIN_REPO=https://gitea.example.com/org/natascha-rieter-nl.git

# Gitea credentials — never commit these; only ever in .env (local) or ~/.env-natascha (server, temporary)
GITEA_HOST=gitea.example.com
GITEA_USER=natascha-deploy
GITEA_TOKEN=your-token-here
```

- [ ] **Step 2: Verify `.env` (your local copy) has matching keys**

Open `.env` and add any keys missing compared to `.env.example`. Fill in real values. Do not change `.env.example` values — they stay as placeholders.

- [ ] **Step 3: Commit `.env.example`**

```bash
git add .env.example
git commit -m "config: update env.example with USER_REPO, MAIN_REPO, SITE_CONFIG_DIR"
```

---

### Task 2: Migrate `user/` from git subtree to standalone nested repo

The `user/` directory is currently tracked by the main repo via git subtree. We convert it to a standalone git repo so `content-push`/`content-pull` are simple `git push`/`git pull` operations.

**Files:**
- Modify: `.gitignore` (root of `site-ai/`)
- No code files changed

- [ ] **Step 1: Push current user/ state via old method (safety sync)**

```bash
cd /path/to/site-ai
git subtree push --prefix=user user-deploy main
```

Expected: pushes current user/ state to Gitea. If this fails because nothing changed, that's fine.

- [ ] **Step 2: Remove user/ from main repo tracking**

```bash
git rm -r --cached user/
```

Expected: output like `rm 'user/config/site.yaml'` for each file. The files stay on disk.

- [ ] **Step 3: Add user/ to .gitignore**

Create or edit `.gitignore` in the `site-ai/` root and add:

```
/user/
```

- [ ] **Step 4: Remove the old user-deploy git remote**

```bash
git remote remove user-deploy
```

Expected: no output, no error.

- [ ] **Step 5: Commit the removal**

```bash
git add .gitignore
git commit -m "chore: remove user/ from main repo tracking (now standalone git repo)"
```

- [ ] **Step 6: Clone user repo fresh into user/**

Replace `$USER_REPO` with the value from your `.env`.

```bash
rm -rf user/
git clone $USER_REPO user/
```

Expected: `user/` is now a proper git repo with its own `.git/` directory, tracking Gitea.

- [ ] **Step 7: Verify**

```bash
git -C user status
git -C user remote -v
```

Expected: clean working tree, remote `origin` pointing to Gitea user repo.

---

### Task 3: Update Makefile — content sync and variable defaults

Replace subtree-based targets with direct git push/pull. Allow `.env` to override `WEBROOT` and `SITE_CONFIG_DIR`.

**Files:**
- Modify: `Makefile`

- [ ] **Step 1: Replace the full Makefile**

```makefile
-include .env
export

SSH := $(REMOTE_USER)@$(REMOTE_HOST)
WEBROOT ?= $(REMOTE_HOME)/public_html
SITE_CONFIG_DIR ?= $(REMOTE_HOME)/site-config

# ── Local dev ──────────────────────────────────────────────────────────────────

start:
	docker compose up -d

stop:
	docker compose down

setup: start install-plugins

install-plugins:
	docker exec natascha_grav php /app/www/public/bin/gpm install $(shell cat plugins.txt | tr '\n' ' ') -y

# ── Content sync (user repo ↔ Gitea) ──────────────────────────────────────────

content-push:
	git -C user push origin main

content-pull:
	git -C user pull origin main

# ── Remote credentials ─────────────────────────────────────────────────────────

remote-env-setup:
	@ssh $(SSH) "printf 'GITEA_HOST=%s\nGITEA_USER=%s\nGITEA_TOKEN=%s\n' \
		'$(GITEA_HOST)' '$(GITEA_USER)' '$(GITEA_TOKEN)' > ~/.env-natascha && chmod 600 ~/.env-natascha"
	@echo "Credentials written to server. Run 'make remote-env-remove' when done."

remote-env-remove:
	@ssh $(SSH) "rm -f ~/.env-natascha"
	@echo "Credentials removed from server."

# ── Remote: initial install ────────────────────────────────────────────────────

remote-install:
	ssh $(SSH) "WEBROOT=$(WEBROOT) \
		SITE_CONFIG_DIR=$(SITE_CONFIG_DIR) \
		USER_REPO=$(USER_REPO) \
		MAIN_REPO=$(MAIN_REPO) \
		GRAV_VERSION=$(GRAV_VERSION) \
		PLUGINS='$(shell cat plugins.txt | tr '\n' ' ')' \
		GITEA_HOST=$(GITEA_HOST) \
		GITEA_USER=$(GITEA_USER) \
		GITEA_TOKEN=$(GITEA_TOKEN) \
		bash -s" < scripts/server-install.sh

# ── Remote: ongoing maintenance ────────────────────────────────────────────────

remote-fetch:
	ssh $(SSH) "git -C $(SITE_CONFIG_DIR) pull"

remote-install-plugins:
	ssh $(SSH) "cd $(WEBROOT) && php bin/gpm install $(shell cat plugins.txt | tr '\n' ' ') -y"

remote-upgrade-grav:
	ssh $(SSH) "cd $(WEBROOT) && php bin/grav upgrade"

remote-clean:
	ssh $(SSH) "cd $(WEBROOT) && php bin/grav clearcache"

remote-maintenance-on:
	ssh $(SSH) "bash -s on $(WEBROOT)" < scripts/server-maintenance.sh

remote-maintenance-off:
	ssh $(SSH) "bash -s off $(WEBROOT)" < scripts/server-maintenance.sh
```

> Note: indentation in Makefiles must be tabs, not spaces.

- [ ] **Step 2: Verify Make parses without errors**

```bash
make -n start
```

Expected: prints `docker compose up -d`, no errors.

- [ ] **Step 3: Commit**

```bash
git add Makefile
git commit -m "feat: overhaul Makefile with full deployment toolchain"
```

---

### Task 4: Update `scripts/server-install.sh`

Add `SITE_CONFIG_DIR` and `MAIN_REPO` variables, clone the main repo to `SITE_CONFIG_DIR`, rename `REPO` → `USER_REPO`, print SSH public key at the end for Gitea deploy key setup.

**Files:**
- Modify: `scripts/server-install.sh`

- [ ] **Step 1: Replace the full script**

```bash
#!/bin/bash
set -e

: "${WEBROOT:?WEBROOT is not set}"
: "${SITE_CONFIG_DIR:?SITE_CONFIG_DIR is not set}"
: "${USER_REPO:?USER_REPO is not set}"
: "${MAIN_REPO:?MAIN_REPO is not set}"
: "${GRAV_VERSION:?GRAV_VERSION is not set}"
: "${PLUGINS:?PLUGINS is not set}"
: "${GITEA_HOST:?GITEA_HOST is not set}"
: "${GITEA_USER:?GITEA_USER is not set}"
: "${GITEA_TOKEN:?GITEA_TOKEN is not set}"

echo "==> Setting up credentials (temporary)"
printf 'machine %s\nlogin %s\npassword %s\n' "$GITEA_HOST" "$GITEA_USER" "$GITEA_TOKEN" > ~/.netrc
chmod 600 ~/.netrc

echo "==> Downloading Grav $GRAV_VERSION"
cd "$WEBROOT"
wget -q "https://getgrav.org/download/core/grav-admin/$GRAV_VERSION" -O grav-admin.zip
unzip -q grav-admin.zip
mv grav-admin/* grav-admin/.htaccess .
rm -rf grav-admin grav-admin.zip

echo "==> Cloning user repo"
rm -rf user
git clone "$USER_REPO" user

echo "==> Cloning main config repo to $SITE_CONFIG_DIR"
mkdir -p "$SITE_CONFIG_DIR"
git clone "$MAIN_REPO" "$SITE_CONFIG_DIR"

echo "==> Installing plugins"
php bin/gpm install $PLUGINS -y

echo "==> Setting permissions"
find "$WEBROOT" -type f -exec chmod 664 {} \;
find "$WEBROOT" -type d -exec chmod 775 {} \;

echo "==> Removing temporary credentials"
rm -f ~/.netrc

echo ""
echo "==> Done."
echo ""
echo "NEXT STEP — add this server's SSH public key to both Gitea repos as a deploy key"
echo "so that 'make remote-fetch' and future git pulls work without credentials:"
echo ""
cat ~/.ssh/id_rsa.pub 2>/dev/null || cat ~/.ssh/id_ed25519.pub 2>/dev/null || \
    echo "  No SSH key found. Generate one on the server: ssh-keygen -t ed25519 -C 'server-deploy'"
echo ""
echo "Visit your domain to complete Grav setup."
```

- [ ] **Step 2: Commit**

```bash
git add scripts/server-install.sh
git commit -m "feat: server-install clones both repos, removes credentials after use"
```

---

### Task 5: Create `scripts/server-maintenance.sh`

Toggle Grav's built-in maintenance mode by setting `pages.offline` in `user/config/system.yaml`. Grav serves its built-in offline page when this is `true`.

**Files:**
- Create: `scripts/server-maintenance.sh`

- [ ] **Step 1: Create the script**

```bash
#!/bin/bash
set -e

MODE="$1"
WEBROOT="$2"
CONFIG="$WEBROOT/user/config/system.yaml"

if [ "$MODE" != "on" ] && [ "$MODE" != "off" ]; then
    echo "Usage: server-maintenance.sh on|off <webroot>"
    exit 1
fi

[ -f "$CONFIG" ] || { echo "Not found: $CONFIG"; exit 1; }

VALUE="false"
[ "$MODE" = "on" ] && VALUE="true"

if grep -q "^\s*offline:" "$CONFIG"; then
    sed -i "s/^\(\s*\)offline: .*/\1offline: $VALUE/" "$CONFIG"
else
    printf '\npages:\n  offline: %s\n' "$VALUE" >> "$CONFIG"
fi

echo "Maintenance mode: $MODE (offline: $VALUE)"
```

- [ ] **Step 2: Make executable**

```bash
chmod +x scripts/server-maintenance.sh
```

- [ ] **Step 3: Verify the script parses cleanly**

```bash
bash -n scripts/server-maintenance.sh
```

Expected: no output, exit 0.

- [ ] **Step 4: Commit**

```bash
git add scripts/server-maintenance.sh
git commit -m "feat: add server-maintenance.sh to toggle Grav offline mode"
```

---

### Task 6: Update `README.md`

Full rewrite. Covers every Make command (one-line description each), setup guide, content sync workflow, and security notes.

**Files:**
- Modify: `README.md`

- [ ] **Step 1: Replace README.md**

```markdown
# natascha-rieter.nl — Grav CMS

Grav CMS site for natascha-rieter.nl. Local dev via Docker; production on a VPS managed entirely through `make`.

---

## Repository structure

Two git repos:

| Repo | Contents | Location |
|------|----------|----------|
| `natascha-rieter-nl` (this repo) | Docker setup, Makefile, scripts, plugins.txt | `site-ai/` |
| `natascha-rieter.nl-user` | Site config, pages, theme | `user/` (nested git repo) |

The `user/` directory is a standalone git repo — its changes are pushed/pulled independently to Gitea. The Grav Sync plugin on the server automatically pulls from Gitea when content is pushed.

---

## Prerequisites

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

---

## Local development setup

```bash
cp .env.example .env   # fill in your values
make setup             # start Docker, install plugins
```

Site runs at http://localhost:8080.

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`, set all values.

2. **Run the install:**

```bash
make remote-install
```

This SSHes into the server, downloads Grav, clones both repos, 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 deploy key to both Gitea repos (read access is enough for `remote-fetch`; the user repo also needs write if Git Sync pushes back).

After this, `make remote-fetch` works without credentials.

---

## Content sync workflow

Editors push content via the Grav Admin panel (or directly edit files in `user/`). The Grav Sync plugin on the server syncs automatically to Gitea.

To pull those changes locally:

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

To push local changes back to Gitea (and trigger server sync):

```bash
git -C user add -A && git -C user commit -m "content: ..."
make content-push   # push local user/ changes → Gitea
```

---

## All commands

### Local

| Command | Description |
|---------|-------------|
| `make start` | Start the local Docker container |
| `make stop` | Stop the local Docker container |
| `make setup` | Start container and install all plugins |
| `make install-plugins` | (Re)install plugins from `plugins.txt` in the local container |
| `make content-push` | Push local `user/` commits to Gitea |
| `make content-pull` | Pull latest `user/` content from Gitea |

### Remote credentials

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

Always run `make remote-env-remove` when done with operations that required it.

### Remote server management

| Command | Description |
|---------|-------------|
| `make remote-install` | First-time install: download Grav, clone both repos, install plugins |
| `make remote-fetch` | Pull latest main 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 Grav maintenance mode (site shows offline page) |
| `make remote-maintenance-off` | Disable Grav maintenance mode |

### Typical upgrade workflow

```bash
make remote-maintenance-on
make remote-env-setup
make remote-fetch
make remote-upgrade-grav
make remote-install-plugins
make remote-env-remove
make remote-maintenance-off
make remote-clean
```

---

## 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`

---

## Security

- `.env` is gitignored. Never commit it.
- `GITEA_TOKEN` exists only in `.env` locally and in `~/.env-natascha` on the server during active sessions. Always run `make remote-env-remove` after use.
- `~/.env-natascha` has `chmod 600` — readable only by the SSH user.
- The server pulls from Gitea using its SSH key (deploy key, read-only). No long-lived token is stored on the server.
- `scripts/server-install.sh` writes `~/.netrc` for the initial clone and deletes it immediately after.
- Credentials are never passed as command-line arguments (they would appear in `ps` output). They are passed as environment variables in the SSH session.
```

- [ ] **Step 2: Commit**

```bash
git add README.md
git commit -m "docs: rewrite README with full command reference, setup guide, security notes"
```

---

## Self-Review

**Spec coverage:**
- ✅ Update initial install to set up both repos
- ✅ content-push/pull interact with Gitea via git (Grav Sync handles server side)
- ✅ remote-fetch (pull main repo changes on server)
- ✅ remote-upgrade-grav
- ✅ remote-install-plugins
- ✅ remote-maintenance-on / remote-maintenance-off
- ✅ remote-env-setup / remote-env-remove
- ✅ No persistent env files on server
- ✅ Make-first, bash only in scripts
- ✅ SSH built from env vars
- ✅ README updated with every command

**Placeholder scan:** None found.

**Type consistency:** N/A (shell/make, no typed interfaces).