example.env

# The one template for every configuration value this repository reads or writes.
#
# WHAT EACH VALUE MEANS IS IN ENVIRONMENT.md, which is the one place it is described.
# This file states the shape and a placeholder. Add a value here and describe it there,
# or checks/check-env-docs.py fails.
#
# It fills two destinations, marked below, because a value belongs to whichever machine
# holds it. Copy the section you need rather than the whole file.
#
#   secrets/<server>.<environment>.env   on a workstation, one file per environment
#   /etc/vps-backup-pull.env             on the backup host, or let ops/install.sh write it
#
# A value appearing in both sections is spelled the same way in both, deliberately. One
# name per thing means the side that writes and the side that reads cannot disagree, which
# is also why ops/install.sh copies values across rather than translating them.
#
# Naming convention: the prefix names whatever owns the value, not whatever reads it.
# HUGO_ is fixed by Hugo, DEPLOY_ is the release tooling, CADDY_ is the container,
# PANGOLIN_ is the proxy, VPS_ is the server, and a *_ROOT is a directory on this host.

# =============================================================================
# secrets/<server>.<environment>.env
# =============================================================================
# One file per environment, named for the server it describes and the environment on it,
# with both words spelled out, and selected by ENV_FILE:
#   secrets/local.production.env   the default, read when ENV_FILE is unset
#   secrets/local.staging.env      ENV_FILE=secrets/local.staging.env deploy/make-release.sh
#   secrets/vps.production.env     ENV_FILE=secrets/vps.production.env deploy/make-release.sh
#   secrets/vps.staging.env        ENV_FILE=secrets/vps.staging.env deploy/make-release.sh
#
# Sourced with `set -a`, which overwrites a variable the caller exported first. A named
# file that does not exist is a hard failure rather than a fall-through. The whole
# secrets/ directory is gitignored, so no value naming a machine reaches this history.

# Where a release is written. The first argument to make-release.sh wins over it.
DEPLOY_ROOT=/path/to/deploy/root

# The site base URL. Must be set for anything that is not production.
HUGO_BASEURL=https://blog.example.com/

# The container's persistent state root, outside DEPLOY_ROOT. Nothing reads it.
CADDY_APPDATA=/path/to/container/appdata

# The container serving this environment.
CADDY_CONTAINER=blog-production

# The environment that must answer, compared against the X-Blog-Env header.
EXPECT_SITE_ENV=production

# Resource access token for an environment behind the auth gate. Set both or neither.
PANGOLIN_ACCESS_TOKEN_ID=
PANGOLIN_ACCESS_TOKEN=

# Read by the deploy workflow, which resolves them from the GitHub Environment rather than
# a file. Named here so the local file and the environment describe the same shape.
# A local run deploys to a path and needs none of them.
#DEPLOY_SSH_HOST=
#DEPLOY_SSH_USER=
#DEPLOY_SSH_KNOWN_HOSTS=

# Environment-independent, so these belong in the default file only.

# The provenance capture, holding the exports and the crawl of the old platform.
# Every script under capture/ reads beneath it, and all but build-redirects.py write there
# too. That one writes the committed maps under deploy/maps/ in the repository.
CAPTURE_ROOT=/path/to/blog-capture

# The old platform's base URL, the site the crawl and the URL verification ran against.
# NOT HUGO_BASEURL, which is where this site is served now. See ENVIRONMENT.md.
CAPTURE_SOURCE_URL=https://blog.example.com

# The old platform's REST API for that site, carrying its numeric site id.
CAPTURE_SOURCE_API=https://public-api.wordpress.com/rest/v1.1/sites/00000000

# The old platform's author slug. Unset, capture/classify.py skips the author-archive
# backfill and says so, rather than emitting a list that is silently short.
CAPTURE_AUTHOR_SLUG=

# The VPS administrative login, NOT the confined deploy account.
VPS_SSH_HOST=root@vps.example.com

# Today's live access log on the VPS, read over SSH and never pulled.
VPS_TRAEFIK_LOG=/var/log/traefik/access.log

# The two agent channel files on the VPS.
VPS_COMMS_DIR=/srv/agent-comms

# =============================================================================
# Both destinations
# =============================================================================
# These name the off-host copy, so the pull writes them and the log review reads them.

# Off-host archives and the plaintext hostconfig tree beside them.
BACKUP_ARCHIVE_ROOT=/path/to/backup/vps

# Off-host copy of the rotated logs. Mode 700, since query strings are logged in full.
LOG_ARCHIVE_ROOT=/path/to/backup/vps-logs

# The rotated access logs on the VPS, and the source of that copy.
VPS_TRAEFIK_LOG_ARCHIVE=/var/log/traefik/archive

# =============================================================================
# /etc/vps-backup-pull.env
# =============================================================================
# On the backup host. Also needs VPS_SSH_HOST and the three values above.
#
# systemd parses this file itself rather than passing it to a shell, so there is no
# expansion and no command substitution: a $ or a backtick is a literal character. It does
# strip matching quotes, which is why a value containing spaces is quoted and arrives
# without them.
#
# VPS_SSH_HOST, BACKUP_ARCHIVE_ROOT and LOG_ARCHIVE_ROOT have no defaults in the pull. An
# address and a destination belong to one host, and a wrong-but-valid destination is a
# backup nobody can find, so it names what is missing and refuses to run.

# The layout on the VPS, the same for any host running this stack.
VPS_ARCHIVE_DIR=/var/backups/pangolin
VPS_BLOG_LOG_DIR=/var/log/blog/legacy

# Key auth only, since the VPS has password auth disabled.
# Quoted because it contains spaces: this file is sourced by a shell for the secrets/
# half, where a bare value would run everything after the first space as a command.
SSH_OPTS="-o ConnectTimeout=15 -o BatchMode=yes"