tane/site/DEPLOY.md

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)

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):

cd <tane-repo>/site && ./build-legal.sh          # regenerates content/legal/*.md + content/about.*.md

Screenshots (edited the harness or want fresh app shots):

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:

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

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

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/:

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).