Set up
WAYL.
Seven steps, each one building on the last. Most people are done in about five minutes.
What you need
- A machine that stays on: a home server, a NAS, a Raspberry Pi 4 or 5, or a small VPS.
- Docker with the Compose plugin, or Podman (see step 3).
- Optional: a Navidrome (or other Subsonic-compatible) or Plex server with your music.
Check that Docker is ready:
docker compose versionConfigure
Get the code:
git clone https://github.com/acrazypie/wayl.git wayl
cd waylThen make a .env file next to docker-compose.yml. Fill in the fields below to build it. Nothing you type leaves this page.
Save it as .env. WAYL creates a secret key the first time it starts and keeps it in the data volume.
Start WAYL
docker compose up -dThat starts two containers from the same image:
- wayl is the web app. It updates its database every time it starts.
- worker keeps your servers in sync in the background: the library every 12 hours, Plex plays every 5 minutes, Navidrome's now playing every minute, and playlists every 6 hours.
Check that it's running:
curl http://localhost:8000/healthzpodman build --format docker -t wayl:latest . && podman compose up -dMake your account
Open your WAYL address and sign up with an email and password. Everyone in your home can make their own account, and each person's servers, plays and playlists stay separate.
Try searching for a song and logging it. That works before you connect a server.
Connect your music server
In WAYL, open Settings → Music servers.
- Enter Navidrome's address as WAYL's container sees it:
http://navidrome:4533if both run in the same Compose project, otherwise its network address. - Enter your Navidrome username and password. WAYL stores the password encrypted and only ever sends Navidrome a salted hash of it.
Optional, for instant logging: send Navidrome's ListenBrainz plays to WAYL.
ND_LISTENBRAINZ_BASEURL=http://192.168.1.20:8000/listenbrainz/1/- Add that line to Navidrome's settings and restart Navidrome. It applies to the whole Navidrome server.
- In WAYL, go to Settings → Scrobbling → Create token.
- In Navidrome, go to Personal settings → Scrobble to ListenBrainz and paste the token.
Without this, WAYL checks Navidrome's now playing list every minute, so songs shorter than a minute can be missed.
- Click Sign in with Plex, approve WAYL in the Plex window, then pick a server.
- WAYL tries each of the server's addresses, local ones first, and keeps the first one that works.
- If none work from inside Docker, choose Enter address and token instead and use something like
http://plex:32400with your Plex token.
WAYL imports your plays from Plex's history: the last 30 days on the first sync, then only new ones. You don't need Plex Pass.
Use it away from home
To use WAYL on your phone, or to share links with friends later, your WAYL has to be reachable from outside your home network. You can do that in two ways:
- Privately with Tailscale or a similar private network. Only your own devices and people you invite can reach it, and you don't have to open any ports.
- Publicly through a reverse proxy with HTTPS on your own domain. Caddy is the simplest option:
# Caddyfile
music.example.com {
reverse_proxy localhost:8000
}Then set APP_URL=https://music.example.com and TRUST_PROXY_HOPS=1 (the reverse proxy switch in step 2 does this), and run docker compose up -d again.
Update & back up
To update to the latest version:
git pull && docker compose up -d --buildBack up the wayl-data volume. It holds your database and the key that encrypts your saved server logins. If you lose that key, you'll have to reconnect your servers and everyone will have to sign in again.
docker run --rm -v wayl_wayl-data:/data -v "$PWD":/backup alpine \
tar czf /backup/wayl-backup.tgz -C /data .Docker puts the folder name in front of the volume name, so it's wayl_ if you cloned into wayl. Run docker volume ls to check.
docker compose logs --tail=50.