From 3d83441388a671364c2c9b4e0fc571406d279153 Mon Sep 17 00:00:00 2001
From: Nick Yeoman <c@nickyeoman.com>
Date: Thu, 2 Jul 2026 21:41:48 -0700
Subject: [PATCH] added spotdl

---
 spotdl_dev/README.md    | 66 +++++++++++++++++++++++++++++++++++++++++
 spotdl_dev/compose.yaml | 15 ++++++++++
 spotdl_dev/sample.env   |  3 ++
 3 files changed, 84 insertions(+)
 create mode 100644 spotdl_dev/README.md
 create mode 100644 spotdl_dev/compose.yaml
 create mode 100644 spotdl_dev/sample.env

diff --git a/spotdl_dev/README.md b/spotdl_dev/README.md
new file mode 100644
index 0000000..34b3ba5
--- /dev/null
+++ b/spotdl_dev/README.md
@@ -0,0 +1,66 @@
+# spotDL
+
+## Overview
+
+spotDL is a command-line music downloader that finds Spotify tracks on YouTube and downloads them with album art, lyrics, and metadata. This stack runs the optional web UI, providing a browser interface where you can paste Spotify links to download tracks, albums, or playlists.
+
+## Project Details
+
+- **Project Repository:** [https://github.com/spotDL/spotify-downloader](https://github.com/spotDL/spotify-downloader)
+- **Container Image:** [spotdl/spotify-downloader](https://hub.docker.com/r/spotdl/spotify-downloader)
+- **Web UI Port:** `8800`
+
+## Getting Started
+
+Open http://localhost:8800 in your browser:
+
+1. Find a Spotify track, album, or playlist URL
+2. Paste it into the spotDL web UI
+3. Click download — spotDL finds the song on YouTube and saves it as an MP3 with full metadata
+
+Downloaded files appear in the `/music` volume.
+
+## Environment Variable Notes
+
+| Variable | Description |
+|---|---|
+| `SPOTDL_IMAGE` | Container image (default: `spotdl/spotify-downloader:latest`) |
+| `SPOTDL_RESTART` | Restart policy (default: `unless-stopped`) |
+| `SPOTDL_PORT` | Published port for the web UI (default: `8800`) |
+| `VOL_PATH` | Base path for persistent data volumes (default: `/data`) |
+
+## Volume Notes
+
+| Volume | Purpose |
+|---|---|
+| `${VOL_PATH:-/data}/spotdl/music` | Downloaded music files |
+
+## Network Notes
+
+Requires an external `proxy` network. Create it once with:
+
+```bash
+docker network create proxy
+```
+
+## Docker Run
+
+```bash
+docker run -d \
+  --name=spotdl \
+  -p 8800:8800 \
+  -v ${VOL_PATH:-/data}/spotdl/music:/music \
+  --network proxy \
+  --restart unless-stopped \
+  spotdl/spotify-downloader:latest \
+  web
+```
+
+## Dockhand Stack, Deploy from Git
+
+- **Cookbooks Repository**
+- **stackname:** spotdl_dev
+- **Compose file path:** spotdl_dev/compose.yaml
+- **Additional env file (optional):** spotdl_dev/sample.env
+
+Load `spotdl_dev/sample.env` into the Environment variables in Dockhand, then create the Stack.
diff --git a/spotdl_dev/compose.yaml b/spotdl_dev/compose.yaml
new file mode 100644
index 0000000..b68787c
--- /dev/null
+++ b/spotdl_dev/compose.yaml
@@ -0,0 +1,15 @@
+services:
+  spotdl:
+    image: ${SPOTDL_IMAGE:-spotdl/spotify-downloader:latest}
+    restart: ${SPOTDL_RESTART:-unless-stopped}
+    command: web
+    ports:
+      - "${SPOTDL_PORT:-8800}:8800"
+    volumes:
+      - ${VOL_PATH:-/data}/spotdl/music:/music
+    networks:
+      - proxy
+
+networks:
+  proxy:
+    external: true
diff --git a/spotdl_dev/sample.env b/spotdl_dev/sample.env
new file mode 100644
index 0000000..d371d0b
--- /dev/null
+++ b/spotdl_dev/sample.env
@@ -0,0 +1,3 @@
+# spotDL
+VOL_PATH=/data
+SPOTDL_IMAGE=spotdl/spotify-downloader:latest