homelab-blueprint/docker-compose-files/youtarr

Youtarr

Docker deployment for Youtarr, a self-hosted YouTube downloader with metadata for media servers. Run all commands from the repository root.

Persistent Data

• DOCKERCONFDIR/youtarr/config stores Youtarr configuration.
• DOCKERCONFDIR/youtarr/jobs stores scheduled job state.
• DOCKERCONFDIR/youtarr/server/images stores thumbnails and cached images.
• youtarr_db_data stores the bundled MariaDB database.
• YOUTUBE_OUTPUT_DIR points at the shared video library, which should be mounted to the UNAS youtube_downloads share.

Installation

1. Create .env if it does not exist:

   cp -n .env.sample .env
   

2. Set the required values in .env:

   TZ=Africa/Johannesburg
   PUID=1000
   PGID=1000
   DOCKERCONFDIR=/opt/appdata
   YOUTUBE_OUTPUT_DIR=/mnt/unas/youtube_downloads
   YOUTARR_HOST_PORT=3087
   YOUTARR_DB_ROOT_PASSWORD=<strong-password>
   DOCKERLOGGING_MAXFILE=3
   DOCKERLOGGING_MAXSIZE=10m
   

3. Create the local directories:

   mkdir -p /opt/appdata/youtarr/{config,jobs,server/images}
   chown -R 1000:1000 /opt/appdata/youtarr
   

   If this stack runs inside a Proxmox LXC, bind-mount /mnt/unas/youtube_downloads into the container before starting Docker.

4. Render the template:

   ./substitute_env.sh docker-compose-files/youtarr/template.yaml docker-compose.youtarr.yml .env
   

5. Validate and start the stack:

   docker compose -f docker-compose.youtarr.yml config --quiet
   docker compose -f docker-compose.youtarr.yml up -d
   

6. Open Youtarr at http://<HOST_IP>:3087.

Apply Configuration Changes

./substitute_env.sh docker-compose-files/youtarr/template.yaml docker-compose.youtarr.yml .env
docker compose -f docker-compose.youtarr.yml up -d

Network Requirements

• YOUTARR_HOST_PORT=3087 publishes the app on host port 3087. The container-side port remains 3011, as required by the upstream image, so the Compose mapping is 3087:3011 (HOST:CONTAINER).
• The video output directory must be mounted and writable before the stack starts.

Troubleshooting

• If MariaDB migration errors mention bind-mount corruption, keep the bundled youtarr_db_data named volume instead of switching the database to a host bind mount.
• If downloads do not appear, confirm YOUTUBE_OUTPUT_DIR points at the host mount that backs the youtube_downloads share.