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 <noreply@anthropic.com>

Author: joshdev8

.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=

.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

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.

docker-compose.yml

@@ -1,3 +1,5 @@
+name: autoplexx
+
 services:
   # ============ MEDIA SERVER ============
   plex: