what it does sharing setup guide github ↗

Set up
WAYL.

Seven steps, each one building on the last. Most people are done in about five minutes.

1

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 version
2

Configure

Get the code:

git clone https://github.com/acrazypie/wayl.git wayl
cd wayl

Then make a .env file next to docker-compose.yml. Fill in the fields below to build it. Nothing you type leaves this page.

Your server's network IP and port, or your domain, like https://music.example.com

Save it as .env. WAYL creates a secret key the first time it starts and keeps it in the data volume.

3

Start WAYL

docker compose up -d

That 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/healthz
Using Podman? Build the image in Docker format first so the health check is kept: podman build --format docker -t wayl:latest . && podman compose up -d
4

Make 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.

5

Connect your music server

In WAYL, open Settings → Music servers.

  1. Enter Navidrome's address as WAYL's container sees it: http://navidrome:4533 if both run in the same Compose project, otherwise its network address.
  2. 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/
  1. Add that line to Navidrome's settings and restart Navidrome. It applies to the whole Navidrome server.
  2. In WAYL, go to Settings → Scrobbling → Create token.
  3. 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.

Once your server is connected, songs you own get an owned mark and a play button that streams them in the browser. To search only your own music, turn on In my library in Search.
6

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.

7

Update & back up

To update to the latest version:

git pull && docker compose up -d --build

Back 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.

Stuck? Open an issue with what you tried and the output of docker compose logs --tail=50.