Operations
Read Host Access Notes before touching a live host. It
records verified connection details, which hosts are reachable only through pve-dell,
and per-host gotchas — all checked directly against the machines rather than assumed.
The rules that prevent most incidents
Section titled “The rules that prevent most incidents”Changes flow through git, not the host
Section titled “Changes flow through git, not the host”/root/infrastructure-toolkit on the traefik host is a checkout tracking main. The
supported path for any change is:
commit → push → git pull on the host → recreateEditing files directly on a host works exactly once. The next git pull conflicts, and
now the host and the repo disagree about what is deployed.
Recreating a container needs BWS
Section titled “Recreating a container needs BWS”bws run --access-token "$BWS_ACCESS_TOKEN" -- docker compose up -d <service>Several required variables are absent from the host .env and exist only in Bitwarden
Secrets Manager. A bare docker compose up -d starts the container with those variables
empty — on traefik, that means empty Proxmox credentials and every
@plugin-traefik-proxmox-provider router disappearing.
docker restart is not up -d
Section titled “docker restart is not up -d”docker restart reuses the existing container definition. Edited compose command:
flags, changed images, and changed environment are all ignored. Only up -d recreates.
Traefik config: know which half you changed
Section titled “Traefik config: know which half you changed”| Config | Applies |
|---|---|
/mnt/lxcshare/docker-data/traefik/dynamic/ | Hot-reloads, no restart needed |
Compose command: flags (static config) | Requires a full up -d recreate |
Never place backups inside the dynamic directory — the file provider parses everything there and duplicate definitions conflict. Back up to a path outside any watched directory.
Working method on live hosts
Section titled “Working method on live hosts”Inspect read-only as much as you like. For anything that mutates state:
- Stage the change
- Validate it
- Confirm before applying
- Back up to a path outside any watched directory
Keeping these notes current
Section titled “Keeping these notes current”Host Access Notes is the durable record. When you learn
something lasting about reaching or operating a host, add it to .claude/host-access.md
in the repo rather than re-deriving it next time. It appears here automatically on the
next build.
No secrets belong in that file — hostnames, IPs, usernames and paths only.