m038/natascha-rieter-nl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync local state with remote after untracked local evolution

Browse Source 
Local site-ai/ had diverged significantly from the last commit pushed
to Gitea (new remote-env-setup/remove targets, SITE_CONFIG_DIR/MAIN_REPO
split, credential cleanup in server-install.sh, migration docs) without
ever being committed. This catches the repo up to what's actually on disk.

Also untracks the legacy user/ subtree left over from before content was
split into its own standalone repo (natascha-rieter.nl-user) — user/ is
gitignored here and stays a separate git repo, unaffected by this commit.
This commit is contained in:
m038
2026-08-30 14:48:54 +02:00
parent 9f798daaa3
commit 8c93dfd7c9
106 changed files with 1056 additions and 1081 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
Regular → Executable
+111 -62
View File
@@ -1,94 +1,143 @@
# natascha-rieter.nl — Grav CMS
## Local development
Grav CMS site for natascha-rieter.nl. Local dev via Docker; production on a VPS managed entirely through `make`.
Requires Docker. To set up from scratch:
---
```
make setup
```
## Repository structure
This starts the container and installs all plugins listed in `plugins.txt` via GPM.
Two git repos:
Other commands:
| 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/` (standalone git repo) |
```
make start # start the container
make stop # stop the container
make install-plugins # (re)install plugins from plugins.txt
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 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:8080.
## Repository structure
Clone the user content repo into `user/` if not already present:
This project uses two git repositories:
| Repo | Contents | Purpose |
|------|----------|---------|
| `natascha-rieter-nl` (this repo) | Docker setup, Makefile, scripts | Local dev and server management |
| `natascha-rieter.nl-user` | Contents of `user/` | Deployed to production, synced with Git Sync |
The `user/` folder in this repo is linked to the user repo via git subtree.
### What goes where
| Path | Description | In git |
|------|-------------|--------|
| `user/config/` | Site and plugin configuration | user repo |
| `user/pages/` | Page content | user repo |
| `user/themes/natascha/` | Custom theme | user repo |
| `user/plugins/` | Plugins (see plugins.txt) | no |
| `user/accounts/` | Admin credentials | no |
| `user/data/` | Runtime data | no |
| `user/cache/` | Generated cache | no |
## Deployment
Production runs on a VPS with Apache. The user repo is cloned into the Grav `user/` folder on the server and kept in sync via the Git Sync plugin.
### Remote config
Copy `.env.example` to `.env` and fill in your values (gitignored):
```
SERVER=user@example.com
WEBROOT=/path/to/public_html
USER_REPO=ssh://git@gitea.example.com/user/repo.git
```bash
git clone $USER_REPO user/
```
### First-time install
---
```
## 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 and runs `scripts/server-install.sh`, which installs Grav and clones the user repo.
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.
### Deploying content changes
**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.
```
make content-push # push local user/ changes to the user repo on Gitea
make content-pull # pull editor's content changes back locally
---
## Content sync workflow
Editors push content via the Grav Admin panel or by editing files in `user/`. The Grav Sync plugin on the server syncs changes automatically to Gitea.
To pull those editor changes locally:
```bash
make content-pull # pull latest user/ content from Gitea → local
```
After `make content-push`, trigger a deploy on the server:
To push local changes to Gitea (triggers server sync):
```
make remote-deploy # pull latest user repo changes and install plugins on server
```bash
git -C user add -A && git -C user commit -m "content: describe change"
make content-push # push local user/ commits → Gitea
```
### Remote maintenance
---
## 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 from plugins.txt |
| `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. 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
```
make remote-install-plugins # install/update plugins from plugins.txt on server
make remote-upgrade-grav # upgrade Grav core on server
make remote-clean # clear Grav cache on server
```
---
## Plugins
Plugins are not committed to git. The full list is in `plugins.txt`.
Plugins are not committed to git. The full list is in `plugins.txt` — one plugin name per line.
- Locally: `make install-plugins`
- Remotely: `make remote-install-plugins`
- On server: `make remote-install-plugins`
---
## 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-natascha` on the server only 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 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.