chore: explicit container_name on every service, document compose v2 migration

Every service now has an explicit container_name, eliminating the
htpc-download-box_ prefix/suffix that compose derived from the directory.
Disambiguated duplicates follow type_context naming:
  postgres_resume / postgres_famapp / postgres_authentik
  minio_resume / minio_famapp
  redis_authentik

Also updates CLAUDE.md and the homelab-ssh skill to reflect:
- compose v2 (docker compose, space) replacing the old v1.27.4 standalone
- dc alias updated to docker compose
- htpc-download-box directory is now clean (legacy cruft removed)

Server-side migration steps (docker-compose-plugin apt install, alias
update, Docker Engine upgrade, old binary removal) are documented in
the session but not yet applied — run apply-compose.ps1 -Compose after
completing them.
This commit is contained in:
ginnoir
2026-06-02 22:58:23 -05:00
parent 41685b3763
commit 20165f48a0
3 changed files with 24 additions and 7 deletions
+4 -4
View File
@@ -16,7 +16,7 @@ Tracked files ↔ where they live on valhalla:
`.env` is committed **intentionally** — the GitHub repo `ginnoir/homelabstack` is private and the stack's secrets are versioned with it. Do not scrub or gitignore it.
The server's `~/htpc-download-box/` also holds unrelated legacy files (`*.bak`, a 2020 `.git`, an old 42 KB `README.md`, `Vagrantfile`, `apache/`, `proxy/`): this stack was grafted onto the original *htpc-download-box* project. Leave that cruft alone — only the three files above are managed from here.
The server's `~/htpc-download-box/` contains only `docker-compose.yml` and `.env` — the legacy cruft from the original *htpc-download-box* project has been cleaned out.
## The core workflow
@@ -43,7 +43,7 @@ SSH is key-based and works from this Windows host directly. In automation, pass
All compose operations go through the **`dc` alias** in the server's `~/.bashrc`:
```
dc = docker-compose -f ~/htpc-download-box/docker-compose.yml --env-file ~/htpc-download-box/.env
dc = docker compose -f ~/htpc-download-box/docker-compose.yml --env-file ~/htpc-download-box/.env
```
It's a shell alias, so it only exists in an **interactive** shell — invoke it over SSH with `bash -ic`:
@@ -59,8 +59,8 @@ Address services by their **compose service name** (`sonarr`, `caddy`, `app`,
## docker-compose.yml — read before editing
- **Compose v1.27.4.** The binary is hyphenated `docker-compose`; `docker compose` (v2) is **not** installed. Project name is `htpc-download-box` (from the directory).
- **Container names:** services with an explicit `container_name:` (most of the media stack, `owncloud_*`, `ntfy`, `freshrss`, `hbbr`/`hbbs`) use that literal name. Services without one get the v1 pattern `htpc-download-box_<service>_1` (e.g. `caddy`, `foundry`, `app`, `postgres`, the `authentik-*`/`famapp-*` sets). Prefer `dc <cmd> <service>` so you don't have to track which is which.
- **Compose v2** (`docker compose`, space), installed as the `docker-compose-plugin` apt package and kept current via apt. Project name is `htpc-download-box` (from the directory — inconsequential since every service now has an explicit `container_name:`).
- **Container names:** every service has an explicit `container_name:`. Disambiguated duplicates use `type_context` naming: `postgres_resume`, `postgres_famapp`, `postgres_authentik`, `minio_resume`, `minio_famapp`, `redis_authentik`. Always use the compose **service name** with `dc` commands — container names are just for `docker ps` readability.
- **`${ROOT}`** (`.env`, default `/`) prefixes some media-stack volume mounts; other services hardcode `/config` and `/storage1`. Both forms resolve to the same real paths.
- **Networks segment the stack:** `foundry`, `media`, `media_external`, `owncloud`, `resume`, `famapp`, `authentik`. `caddy` is the only container on all of them — a new service that Caddy must proxy has to share a network with `caddy`.
- **Persistence lives on the server, not in this repo:** container state is in `/config/<service>` bind mounts, under `/storage1`, or in named volumes (`postgres_data`, `minio_data`, `authentik_db_data`, `garden_uploads`, …).