archive-clients/deploy/production/README.md

Production deployment

These files are the non-secret, host-specific deployment manifests for the initial x1/x2/lithium topology and the later helium archive node.

• Install the x1 and x2 files as ~/compose/ArchiveControl-cache/{compose.yaml,client.toml}.
• Install the lithium files as ~/compose/ArchiveControl-archive/{compose.yaml,client.toml}.
• The helium directory contains three isolated compose-project manifests. Install them under ~/Repositories/compose/{qbittorrent-helium,syncthing-helium,ArchiveControl-archive} as described in helium/README.md.
• Create sibling state, backups, and secrets directories owned by the configured container UID/GID.
• Secret files are never committed. Each secrets directory contains archive_control_token, qb_password, and syncthing_api_key, each a regular non-empty file with mode 0600.

Hardlink-safe bind-mount topology

For an archive source, the qB content path and every Syncthing route used for staging must resolve through the same container mount. Matching host filesystem device IDs alone is insufficient: two separate Docker bind mounts have different mount IDs and link(2) may return EXDEV across them. The client deliberately treats that case as copy-only and performs a full payload free-space check.

Automatic routes always use the Syncthing API path routes/<route-id>. Bind that path from a dedicated directory beneath the qB data root, then map the same path through the qB client mount:

# Syncthing compose project
volumes:
  - /srv/syncthing-config:/var/syncthing
  - /srv/downloads/.archive-control-routes:/var/syncthing/routes

# Archive Control client compose project
volumes:
  - /srv/downloads:/data/qb
  - /srv/syncthing-config:/data/sync

[syncthing]
api_root = "/var/syncthing"
local_root = "/data/sync"
local_path_overrides = { "/var/syncthing/routes" = "/data/qb/.archive-control-routes" }

Do not mount the route directory separately into the client. The override is the authoritative mapping and keeps qB source files and automatic route folders in one mount namespace. Existing manually configured Syncthing folders below the qB tree may retain their own exact overrides. Use API-visible paths, not Syncthing folder IDs, as override keys.

Before starting a stack, validate its config and then run the generic host preflight with that machine's own paths and container names:

docker compose config
docker compose run --rm archive-client --check-config
python3 scripts/preflight-deployment.py --help

The check is fail-fast and performs local permission, filesystem, sparse-file, hard-link, and reflink probes. Normal startup additionally probes the local qBittorrent and Syncthing APIs before registration.

scripts/preflight-deployment.py is deliberately topology-agnostic: pass the host's client.toml and its client, qBittorrent, and Syncthing container names. It resolves Docker mounts rather than assuming project names or host paths. It also catches a common fatal error: a Syncthing api_root that names its config volume rather than the mounted shared-data tree.