Gluetun integration
Gluetun is a powerful Docker container for running a WireGuard or OpenVPN tunnel for your Docker containers or other devices on your network.
Important: Youtarr runs inside Gluetun's network, so the two are tied together.
- To restart Gluetun, run
docker compose restart gluetun. Youtarr restarts with it. - If Gluetun restarts or gets replaced on its own (a crash,
docker restart, a Watchtower update, a Portainer recreate), Youtarr goes offline. Rundocker compose up -d --force-recreate youtarrto reattach it. - Updating Gluetun with
docker compose pull && docker compose up -drecreates Youtarr automatically.
Note: This is a basic guide. Gluetun is pinned to the v3 image to avoid breaking changes. You need Docker Compose v2.24 or newer (check with docker compose version); the old docker-compose v1 command won't work.
Installation
New Youtarr installation
Set up Gluetun before the first start so Youtarr never runs without the VPN. If you already ran ./start.sh once, follow the existing-installation steps below instead.
- Clone the repository and create
.envfrom.env.example, then setYOUTUBE_OUTPUT_DIR(INSTALLATION.md walks through this). - In the Gluetun section at the bottom of
.env, uncommentCOMPOSE_PATH_SEPARATORand theCOMPOSE_FILEline that matches your setup. Then uncomment and fill inVPN_SERVICE_PROVIDER,WIREGUARD_PRIVATE_KEYandWIREGUARD_ADDRESSES. On a fresh install,./start.shadds the named-volume database override to that line for you. - Continue with steps 3 to 6 below, then finish the initial setup in the web UI as described in INSTALLATION.md.
Existing Youtarr installation
-
Back up Youtarr and Youtarr's database
- While adding Gluetun and using the new Docker Compose files does not mess with Youtarr or its database, it is always recommended to back up Youtarr and its database when modifying its setup.
- See BACKUP_RESTORE.md for instructions
-
Copy the Gluetun section from .env.example to the bottom of your existing
.envand set the required variables, such asVPN_SERVICE_PROVIDERWIREGUARD_PRIVATE_KEYWIREGUARD_ADDRESSES
Note: Your
.envmay already have aCOMPOSE_FILE=line (./start.shadds one on named-volume installs). If it does, add:docker-compose.gluetun.ymlto the end of that line. Don't add a secondCOMPOSE_FILEline; Compose only reads the last one. If there isn't one, uncomment theCOMPOSE_FILEline in the Gluetun section that matches your setup. -
Set
FIREWALL_OUTBOUND_SUBNETS(for example192.168.1.0/24) if Youtarr needs to reach Plex, Jellyfin, Emby or an external database on your LAN. Without it, that traffic goes into the VPN and times out.Note:
host.docker.internalpoints at the Docker bridge, not your LAN, so add172.17.0.0/16(or your bridge subnet) if you use it. Enter Plex, Jellyfin and Emby by IP address, not by a LAN hostname: Gluetun blocks DNS answers that point at private IPs. The subnets can't overlap your VPN tunnel's address range. See the Gluetun firewall docs. -
Reverse proxy users (Traefik, NPM, etc.)
- Domain name users will need to point the upstream domain name from your Youtarr instance to Gluetun.
- Example:
youtarr:3011togluetun:3011
- Example:
- IP address users using Docker container IP addresses will need to update the upstream IP address from Youtarr's IP address to Gluetun's container IP address. Youtarr and Gluetun will share the same container IP address, because all of Youtarr's traffic goes through Gluetun.
- Example:
10.88.2.2to10.89.2.2or something similar
- Example:
- IP address users not using Docker container IP addresses will not need to change anything.
- Domain name users will need to point the upstream domain name from your Youtarr instance to Gluetun.
-
Start Youtarr with
./start.sh, ordocker compose up -dif you don't use the scripts. Compose recreates the Youtarr container on its own; no--force-recreateneeded. If you use an external database, rundocker compose up -d:./start-with-external-db.shignoresCOMPOSE_FILEand would start Youtarr without the VPN. -
Check that it worked:
docker compose exec youtarr curl -s https://api.ipify.orgshould print your VPN provider's IP address, not your own.
Sources: