Configure Docker Compose through .env for Arcane

docker-compose.yml now reads every host-specific value (paths, user,
port, network, time zone) from .env with the previous values as
defaults. .env.example documents them; .env stays out of Git.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.dockerignore

@@ -3,3 +3,5 @@ web/node_modules
 web/dist
 config
 *.db
+.env
+.env.*

.env.example

@@ -0,0 +1,39 @@
+# playlink settings for docker-compose.yml.
+# Copy to .env (or paste into Arcane's .env editor) and adjust.
+# Anything left out uses the default shown here.
+
+# ---- container ----
+# Image tag to build/run and the container's name.
+PLAYLINK_IMAGE=playlink:latest
+PLAYLINK_CONTAINER_NAME=playlink
+# Version label shown in the UI footer.
+PLAYLINK_VERSION=dev
+# Restart policy: no, always, on-failure or unless-stopped.
+PLAYLINK_RESTART=unless-stopped
+# Existing Docker network to join (must already exist).
+PLAYLINK_NETWORK=chromanet
+
+# ---- user and time zone ----
+# The user and group that own your music files (Unraid nobody:users = 99:100).
+PUID=99
+PGID=100
+TZ=America/Los_Angeles
+
+# ---- web UI ----
+# Host port for the web UI.
+PLAYLINK_PORT=7480
+# Set to true when serving over HTTPS (e.g. behind a reverse proxy).
+PLAYLINK_SECURE_COOKIES=false
+# info, or debug for verbose logs.
+PLAYLINK_LOG_LEVEL=info
+
+# ---- folders ----
+# Host folder for playlink's database and backups (mounted at /config).
+PLAYLINK_CONFIG_PATH=/mnt/user/Aqua/playlink
+# Host folder that contains BOTH libraries (mounted at /data). Hardlinks
+# can't cross bind mounts, so use one common parent folder, e.g.
+#   master (Albums)  -> /data/Media/Music/Albums
+#   slave  (Singles) -> /data/Media/Music/Instances/cdnutter/Singles
+PLAYLINK_DATA_PATH=/mnt/user/Sapphire
+# Folders inside the container that libraries may use (comma-separated).
+PLAYLINK_ALLOWED_ROOTS=/data

.gitignore

@@ -7,3 +7,6 @@ web/node_modules/
 web/dist/*
 !web/dist/.gitkeep
 web/*.tsbuildinfo
+
+# Local compose settings (see .env.example)
+.env

README.md

@@ -198,21 +198,29 @@ playlink is built so that no user data is ever lost, even if it crashes or loses
 
 ## Quick start (Docker / Unraid)
 
-```yaml
+`docker-compose.yml` takes every host-specific value from a `.env` file next to it, so the compose file itself never needs editing. That
-services:
+suits [Arcane](https://github.com/ofkm/arcane): point a project's Git Sync at this repository and set the values in Arcane's `.env` editor;
-  playlink:
+Arcane builds the image from the `Dockerfile`. With plain Compose:
-    build: .            # or your published image
+
-    container_name: playlink
+```sh
-    user: "99:100"      # owner of your music files (Unraid nobody:users)
+cp .env.example .env    # then edit it
-    ports: ["7480:7480"]
+docker compose up -d --build
-    environment:
-      - PLAYLINK_ALLOWED_ROOTS=/data
-    volumes:
-      - /mnt/user/appdata/playlink:/config
-      - /mnt/user/Sapphire/Media/Music:/data/Music   # ONE mount containing both libraries
-    restart: unless-stopped
 ```
 
+The main settings (all listed with defaults in `.env.example`):
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `PLAYLINK_DATA_PATH` | `/mnt/user/Sapphire` | Host folder containing **both** libraries, mounted at `/data`. |
+| `PLAYLINK_CONFIG_PATH` | `/mnt/user/Aqua/playlink` | Host folder for the database and backups, mounted at `/config`. |
+| `PUID` / `PGID` | `99` / `100` | User and group that own your music (Unraid `nobody:users`). |
+| `PLAYLINK_PORT` | `7480` | Host port of the web UI. |
+| `PLAYLINK_NETWORK` | `chromanet` | Existing Docker network to join. |
+| `TZ` | `America/Los_Angeles` | Time zone for logs and backup schedules. |
+| `PLAYLINK_SECURE_COOKIES` | `false` | `true` behind HTTPS. |
+
+`.env` is ignored by Git, so your settings stay local while the repository syncs.
+
 Then open `http://<server>:7480`, create your account, and add a pair:
 
 - Master: `/data/Music/Albums`

docker-compose.yml

@@ -1,28 +1,34 @@
+# Every host-specific value comes from .env (see .env.example), so the
+# stack can be built and kept in sync by Arcane (or any Compose host)
+# without editing this file. Defaults below apply when a variable is unset.
 services:
   playlink:
-    build: .
+    build:
-    image: playlink:latest
+      context: .
-    container_name: playlink
+      args:
+        VERSION: ${PLAYLINK_VERSION:-dev}
+    image: ${PLAYLINK_IMAGE:-playlink:latest}
+    container_name: ${PLAYLINK_CONTAINER_NAME:-playlink}
     # Run as the user that owns your music (Unraid: nobody:users = 99:100).
-    user: "99:100"
+    user: "${PUID:-99}:${PGID:-100}"
     ports:
-      - "7480:7480"
+      - "${PLAYLINK_PORT:-7480}:7480"
     environment:
-      - TZ=America/Los_Angeles
+      TZ: ${TZ:-America/Los_Angeles}
-      - PLAYLINK_ALLOWED_ROOTS=/data
+      PLAYLINK_ALLOWED_ROOTS: ${PLAYLINK_ALLOWED_ROOTS:-/data}
-      # Set to true when serving over HTTPS (e.g. behind a reverse proxy).
+      PLAYLINK_SECURE_COOKIES: ${PLAYLINK_SECURE_COOKIES:-false}
-      - PLAYLINK_SECURE_COOKIES=false
+      PLAYLINK_LOG_LEVEL: ${PLAYLINK_LOG_LEVEL:-info}
     volumes:
-      - /mnt/user/Aqua/playlink:/config
+      - ${PLAYLINK_CONFIG_PATH:-/mnt/user/Aqua/playlink}:/config
-      # IMPORTANT: mount ONE folder that contains BOTH libraries. Hardlinks
+      # IMPORTANT: ONE folder that contains BOTH libraries. Hardlinks
       # cannot cross Docker bind mounts, even on the same disk.
-      #   master  (Albums)  -> /data/Music/Albums
+      - ${PLAYLINK_DATA_PATH:-/mnt/user/Sapphire}:/data
-      #   slave (Singles) -> /data/Music/Instances/cdnutter/Singles
+    restart: ${PLAYLINK_RESTART:-unless-stopped}
-      - /mnt/user/Sapphire:/data
-    restart: unless-stopped
     networks:
-      - chromanet
+      - playlink
 
 networks:
-  chromanet:
+  playlink:
+    # An existing Docker network (e.g. the one your reverse proxy uses).
+    name: ${PLAYLINK_NETWORK:-chromanet}
     external: true