107 lines
4.6 KiB
Markdown
107 lines
4.6 KiB
Markdown
# Deploying the Tane landing site (tane.comunes.org)
|
|
|
|
Runbook for publishing changes to the landing page. Written so another agent (or
|
|
a human) can reproduce it without prior context.
|
|
|
|
## Architecture (what actually runs)
|
|
|
|
```
|
|
browser ── Cloudflare ── assange (nginx reverse proxy, TLS) ── groucho:8082 ── nginx container (static Hugo site)
|
|
```
|
|
|
|
- The site source lives in this repo under `site/` (Hugo). It is **built into a
|
|
static nginx image on the host** by Ansible — no Hugo on the control node, no
|
|
registry.
|
|
- `site/` builds legal + about pages from `docs/` (single source of truth) and
|
|
serves screenshots generated by the Flutter golden harness.
|
|
- Two separate git repos are involved:
|
|
- **Tane repo** (this one): the `site/` source, docs, and the screenshot harness.
|
|
- **Ansible repo**: `~/proyectos/sync/comunes/shared-l2/ansible` — the deploy
|
|
playbook and the reverse-proxy vhost.
|
|
|
|
## One-time setup (already done; only if starting fresh)
|
|
|
|
```sh
|
|
cd ~/proyectos/sync/comunes/shared-l2/ansible
|
|
ansible-galaxy collection install -r collections/requirements.yml # community.docker + ansible.posix
|
|
# Publish the vhost on the proxy (adds tane.comunes.org). NOT needed for content updates:
|
|
ansible-playbook -i comunes_inventory.ini proxies.yml --tags proxy-loop
|
|
```
|
|
DNS `tane.comunes.org` and the `comunes.org` TLS cert (must cover the subdomain)
|
|
are already in place.
|
|
|
|
## Routine deploy (the common case)
|
|
|
|
### 1. Regenerate derived content (only if you changed the sources)
|
|
|
|
Legal / About text (edited under `docs/legal/**`, `docs/que-es-tane.md`,
|
|
`docs/what-is-tane.md`):
|
|
```sh
|
|
cd <tane-repo>/site && ./build-legal.sh # regenerates content/legal/*.md + content/about.*.md
|
|
```
|
|
|
|
Screenshots (edited the harness or want fresh app shots):
|
|
```sh
|
|
cd <tane-repo>/apps/app_seeds
|
|
flutter test --update-goldens --run-skipped --tags screenshots test/screenshots/screenshots_test.dart
|
|
tool/collect_screenshots.sh # copies PNGs into site/assets/screenshots + fastlane
|
|
```
|
|
(The OG social cards `site/static/og-*.png` are regenerated by hand when the
|
|
inventory shot changes — see the `og-tpl.sh` step in git history; optional.)
|
|
|
|
### 2. Commit & land on main
|
|
|
|
The deploy syncs from the **main checkout** by default, so commit first:
|
|
```sh
|
|
cd <tane-repo> && git add -A && git commit -m "..."
|
|
git -C ~/proyectos/dev/tane merge --ff-only <your-branch> # land on main
|
|
git -C ~/proyectos/dev/tane push origin main
|
|
```
|
|
|
|
### 3. Deploy
|
|
|
|
```sh
|
|
cd ~/proyectos/sync/comunes/shared-l2/ansible
|
|
ansible-playbook -i comunes_inventory.ini tane-landing.yml
|
|
```
|
|
This rsyncs `site/` to `groucho:/data/tane-landing/src`, rebuilds the
|
|
Hugo→nginx image there, and recreates the container (only when the source
|
|
changed). `proxies.yml` does **not** need re-running for content changes.
|
|
|
|
### 4. Verify
|
|
|
|
```sh
|
|
curl -sI https://tane.comunes.org/ | head -1 # 200
|
|
curl -s https://tane.comunes.org/es/about/ | grep -o '<title>[^<]*</title>'
|
|
```
|
|
|
|
## Deploying from a git worktree (not the main checkout)
|
|
|
|
`tane_site_src` defaults to `$HOME/proyectos/dev/tane/site`. To deploy uncommitted
|
|
work from a worktree, point it at that worktree's `site/`:
|
|
```sh
|
|
ansible-playbook -i comunes_inventory.ini tane-landing.yml \
|
|
-e tane_site_src=/abs/path/to/worktree/site
|
|
```
|
|
Prefer landing on main and deploying from the main checkout for reproducibility.
|
|
|
|
## Gotchas
|
|
|
|
- **Cloudflare + assange cache static assets ~16 days by stable URL.** The
|
|
screenshots and CSS are **fingerprinted** (`… | fingerprint` in the Hugo
|
|
templates), so their URLs change with content and bust the cache automatically.
|
|
Fixed-URL assets — `og-*.png`, `favicon*`, `site.webmanifest`, `/logo.png` — are
|
|
NOT fingerprinted: if you change one, either purge Cloudflare or add a `?v=N`.
|
|
Symptom of a stale asset: `curl <url>` returns old bytes but `curl <url>?v=1`
|
|
returns the new ones, and the container file (`docker exec tane-landing ls -l
|
|
/usr/share/nginx/html/...`) is already correct.
|
|
- **Screenshot golden test is skip-by-default** (`dart_test.yaml`), so CI stays
|
|
green; you must pass `--run-skipped --tags screenshots` to run/update it.
|
|
- **main can diverge** (other sessions commit to it). If `merge --ff-only` fails,
|
|
rebase your branch onto main first: `git rebase main` (site changes rarely
|
|
conflict), then FF.
|
|
- **`--check` (dry-run) fails at the compose step** ("/data/tane-landing is not a
|
|
directory") because check mode doesn't create the synced dir — that's expected,
|
|
not a real error; do a real run.
|
|
- Container port is **8082** on groucho, bound `0.0.0.0` (firewall restricts it to
|
|
assange). The proxy vhost lives in `proxies.yml` under `citems` (cert `comunes.org`).
|