From 84494ed49213fc0a25937a29b096566c2665f215 Mon Sep 17 00:00:00 2001 From: Josh Cain Date: Wed, 13 May 2026 09:09:41 -0400 Subject: [PATCH] Cleanup: prune .env, name project, validate compose in CI - .env.example: remove ~dozen vars no service consumes (OPENVPN_*, DOCKER_INFLUXDB_*, RADARR_*/SONARR_* URLs/keys, EMAIL/PASSWORD, HTTP_*, DOMAIN*, TRANSMISSION_USERNAME/PASSWORD, PLEX_ADVERTISE_IP, PLEX_TOKEN, TELEGRAF_CFG_PATH, the bare PATH= line). Group the rest by service with brief comments. Real values must be filled in, not just rely on placeholders. - docker-compose.yml: add top-level `name: autoplexx` so `docker compose` commands aren't sensitive to the directory name when running outside this checkout. - prometheus/prometheus.yml -> docs/prometheus.example.yml. There is still no `prometheus` service in compose; the rename makes its example-only status obvious. - New workflow .github/workflows/compose-validate.yml runs `docker compose config` on every PR that touches compose or .env.example, matching the validation step the CONTRIBUTING guide tells authors to run locally. - CLAUDE.md: update env-var contract (no more "documented but unused" category) and point at the new prometheus path. Co-Authored-By: Claude Opus 4.7 --- .env.example | 118 ++++++------------ .github/workflows/compose-validate.yml | 35 ++++++ CLAUDE.md | 11 +- docker-compose.yml | 2 + .../prometheus.example.yml | 0 5 files changed, 84 insertions(+), 82 deletions(-) create mode 100644 .github/workflows/compose-validate.yml rename prometheus/prometheus.yml => docs/prometheus.example.yml (100%) diff --git a/.env.example b/.env.example index a5b4d3b..a3af739 100644 --- a/.env.example +++ b/.env.example @@ -1,81 +1,45 @@ -## COPY THIS OR RENAME THIS FILE TO ".env" AND REPLACE WITH YOUR SPECIFIC VALUES -## THESE ARE ALL DUMMY VALUES BUT GIVE YOU A GENERAL IDEA OF WHAT THEY SHOULD LOOK LIKE -## for more information on configuration + env variable examples: -## https://docs.linuxserver.io/images/docker-radarr/#docker-compose-recommended-click-here-for-more-info -## (click relevant container for specific info) - -# Basic Configuration -PATH="/usr/local/sbin:/usr/local/bin" -PUID=1000 # Find more about PUID/PGID at https://docs.linuxserver.io/general/understanding-puid-and-pgid -PGID=999 -TZ=America/New_York # See more timezone options at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones -USERDIR=/home/username # Path to your home directory or desired location. - -# Plex Specific -PLEX_ADVERTISE_IP=https://192.168.0.100:32400/ # Needed in Bridge Networking. -PLEX_CLAIM=aksjdfw84348033 # Obtain from https://www.plex.tv/claim. Necessary for server token. -PLEX_TOKEN=aoiwejfj9230403402 # Obtain from https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/ - -# Optional Settings -EMAIL=email@email.com -PASSWORD=password123 -HTTP_USERNAME=fakeusername -HTTP_PASSWORD=fakepassword -DOMAIN=mycustomdomain.com -DOMAINNAME=mycustomdomain.com - -# Transmission Settings -TRANSMISSION_USERNAME=username # Username for logging into transmission frontend -TRANSMISSION_PASSWORD=password123 # Password for logging into transmission frontend - -# OpenVPN Configuration -## more info: https://haugene.github.io/docker-transmission-openvpn/ -OPENVPN_PROVIDER=PIA # (Private Internet Access) -OPENVPN_CONFIG=ca_montreal # Optional line (update this to whichever location you prefer) -OPENVPN_USERNAME=openvpnusername -OPENVPN_PASSWORD=openvpnpassword123 - -# InfluxDB Setup and Operation -DOCKER_INFLUXDB_INIT_MODE=setup -DOCKER_INFLUXDB_INIT_USERNAME=administrator -DOCKER_INFLUXDB_INIT_PASSWORD=password -DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=034838492002jklasjdfasdf # not a real token -DOCKER_INFLUXDB_INIT_ORG=administrator -DOCKER_INFLUXDB_INIT_BUCKET=telegraf -DOCKER_INFLUXDB_INIT_RETENTION=2d # Valid units: ns, us, ms, s, m, h, d, w. -DOCKER_INFLUXDB_INIT_PORT=8086 -DOCKER_INFLUXDB_INIT_HOST=influxdb - -# Telegraf Configuration -TELEGRAF_CFG_PATH=./telegraf/telegraf.conf - -# Grafana Configuration +## Copy this file to ".env" and fill in your values. +## Only the variables in this file are actually read by docker-compose.yml. + +# ============ Common (used by most services) ============ +# PUID/PGID: see https://docs.linuxserver.io/general/understanding-puid-and-pgid +PUID=1000 +PGID=1000 +# Timezone: see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones +TZ=America/New_York +# Parent directory where service configs and media live. Every bind mount +# in docker-compose.yml is rooted here. +USERDIR=/home/username + +# ============ Plex ============ +# Obtain immediately before `docker compose up -d`. Claim tokens expire in +# roughly 4 minutes. See https://www.plex.tv/claim +PLEX_CLAIM= + +# ============ Grafana ============ +# Host port to expose Grafana on. Defaults to 3000 if unset. GRAFANA_PORT=3000 -# Radarr -RADARR_URL=http://192.168.86.1:7878 -RADARR_API_KEY=1234523452345234jlksjdfla - -# Sonarr -SONARR_URL=http://192.168.86.1:8989 -SONARR_API_KEY=28939234kajsdjkfjalsd - -# Kometa (Plex Meta Manager) -PMM_PLEX_URL=http://192.168.86.1:32400 -PMM_PLEX_TOKEN=your_plex_token_here -PMM_TMDB_API_KEY=your_tmdb_api_key_here -PMM_TAUTULLI_URL=http://192.168.86.1:8181 -PMM_TAUTULLI_API_KEY=your_tautulli_api_key_here -PMM_OMDB_API_KEY=your_omdb_api_key_here -PMM_MDBLIST_API_KEY=your_mdblist_api_key_here -PMM_TRAKT_CLIENT_ID=your_trakt_client_id_here -PMM_TRAKT_CLIENT_SECRET=your_trakt_client_secret_here -PMM_TRAKT_ACCESS_TOKEN=your_trakt_access_token_here -PMM_TRAKT_REFRESH_TOKEN=your_trakt_refresh_token_here - -# Tracearr -DB_PASSWORD=your_secure_database_password -JWT_SECRET=your_jwt_secret_here -COOKIE_SECRET=your_cookie_secret_here +# ============ Tracearr (required — stack will refuse to start if blank) ============ +# Use strong random strings, e.g. `openssl rand -base64 32` +DB_PASSWORD= +JWT_SECRET= +COOKIE_SECRET= +# Where the Tracearr UI is reachable from. Adjust if you front it with a +# reverse proxy. CORS_ORIGIN=http://localhost:3001 +# ============ Kometa / Plex Meta Manager ============ +# Only required if you plan to run Kometa against this stack. See README's +# "Kometa Configuration" section. +PMM_PLEX_URL=http://192.168.1.100:32400 +PMM_PLEX_TOKEN= +PMM_TMDB_API_KEY= +PMM_TAUTULLI_URL=http://192.168.1.100:8181 +PMM_TAUTULLI_API_KEY= +PMM_OMDB_API_KEY= +PMM_MDBLIST_API_KEY= +PMM_TRAKT_CLIENT_ID= +PMM_TRAKT_CLIENT_SECRET= +PMM_TRAKT_ACCESS_TOKEN= +PMM_TRAKT_REFRESH_TOKEN= diff --git a/.github/workflows/compose-validate.yml b/.github/workflows/compose-validate.yml new file mode 100644 index 0000000..56587dc --- /dev/null +++ b/.github/workflows/compose-validate.yml @@ -0,0 +1,35 @@ +name: Validate docker compose + +on: + pull_request: + paths: + - 'docker-compose.yml' + - '.env.example' + - '.github/workflows/compose-validate.yml' + push: + branches: [main] + paths: + - 'docker-compose.yml' + - '.env.example' + - '.github/workflows/compose-validate.yml' + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Create .env from example + run: | + cp .env.example .env + # Tracearr's compose entries use the ${VAR:?must be set} form, so + # blank placeholders in .env.example would fail interpolation. Fill + # them with throwaway values just for the validation step. + { + echo "DB_PASSWORD=ci-validation" + echo "JWT_SECRET=ci-validation" + echo "COOKIE_SECRET=ci-validation" + } >> .env + + - name: docker compose config + run: docker compose config --quiet diff --git a/CLAUDE.md b/CLAUDE.md index 3e9463c..ec1a9ba 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,7 +37,7 @@ Radarr and Sonarr are deliberately on both `media_network` (so Seerr, Prowlarr, **Volume paths are intentionally user-specific.** All bind mounts are rooted at `${USERDIR}` from `.env`. When advising the user, do not assume any particular host path layout — the README explicitly tells them to update paths to match their drive mounts. -**Prometheus config is orphaned.** `prometheus/prometheus.yml` exists and references `telegraf:9273` and `tautulli:8181` as scrape targets, but there is no `prometheus` service in `docker-compose.yml`. Treat it as a stub for users who want to add Prometheus themselves — don't assume metrics are being scraped today. +**No Prometheus in the stack.** There is no `prometheus` service in `docker-compose.yml`. A starting-point config lives at `docs/prometheus.example.yml` for users who want to add Prometheus themselves — don't assume metrics are being scraped today. **Transmission VPN is aspirational.** The README claims VPN support and `.env.example` has `OPENVPN_*` variables, but the active image is plain `linuxserver/transmission` with no VPN sidecar or `haugene/transmission-openvpn` config. If the user wants real VPN tunneling, that's a change, not a fix. @@ -56,8 +56,9 @@ The mounted config directory is `plex-meta-manager/config/`. Its structure is re ## Env var contract -`.env.example` is the source of truth for what `.env` needs. The values fall into three categories: +`.env.example` is the source of truth for what `.env` needs, and every var in it is actually consumed by `docker-compose.yml`. The values fall into two categories: -1. **Hard-required** (stack won't start): `DB_PASSWORD`, `JWT_SECRET`, `COOKIE_SECRET` (all Tracearr). -2. **Effectively required for the feature to work**: `PUID`/`PGID`/`TZ`/`USERDIR` (everything), `PLEX_CLAIM` (first-boot only), `PMM_*` (Kometa). -3. **Documented but unused by the current compose file**: `OPENVPN_*`, `DOCKER_INFLUXDB_*`, `RADARR_*`, `SONARR_*`, `EMAIL`/`PASSWORD`/`HTTP_*`/`DOMAIN*`. These exist for the "not included but recommended" services in the README or aspirational features — don't add validation for them and don't assume the user has them set. +1. **Hard-required** (stack won't start): `DB_PASSWORD`, `JWT_SECRET`, `COOKIE_SECRET` (all Tracearr — they use the `${VAR:?must be set}` fail-fast form). +2. **Effectively required for the feature to work**: `PUID`/`PGID`/`TZ`/`USERDIR` (everything), `PLEX_CLAIM` (first-boot only), `GRAFANA_PORT` (defaults to 3000 if unset), `PMM_*` (Kometa). + +If a user mentions an env var not in this list (e.g. `OPENVPN_*`, `RADARR_API_KEY`, `DOCKER_INFLUXDB_*`), it's from an older version of the stack — not consumed today. diff --git a/docker-compose.yml b/docker-compose.yml index 457d451..d42e05f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,3 +1,5 @@ +name: autoplexx + services: # ============ MEDIA SERVER ============ plex: diff --git a/prometheus/prometheus.yml b/docs/prometheus.example.yml similarity index 100% rename from prometheus/prometheus.yml rename to docs/prometheus.example.yml