How to Deploy Navidrome on a VPS

#Install Navidrome (Docker Compose)

#Permissions first

Navidrome needs read-write access to /data (its database and cache), read access to /music, and upstream is firm that it should not run as root. The image uses a user: directive — the PUID/PGID variables you may know from linuxserver images have no effect here. So create the folders as your own user and record your IDs:

copymkdir -p ~/navidrome && cd ~/navidrome
mkdir -p data music backup
printf 'PUID=%s\nPGID=%s\n' "$(id -u)" "$(id -g)" > .env

#The password encryption key

To stay compatible with the Subsonic API, Navidrome has to store user passwords in a recoverable form. By default it encrypts them with a shared key that is in the public source code, which is obfuscation rather than protection. Setting your own PasswordEncryptionKey fixes that — and upstream warns it is a one-time setting: once passwords are encrypted with it, changing it locks users out. Set it now, before the first user exists:

copycd ~/navidrome
grep -q ND_PASSWORDENCRYPTIONKEY .env || echo "ND_PASSWORDENCRYPTIONKEY=$(openssl rand -hex 32)" >> .env

Keep a copy of .env with your backups. Without that key, a restored database has passwords nobody can use.

#The compose file

This is upstream's compose example with the port on loopback, the music mounted read-only, and automatic database backups turned on:

copycd ~/navidrome
cat > docker-compose.yml <<'YAML'
services:
  navidrome:
    image: deluan/navidrome:latest
    container_name: navidrome
    user: "${PUID}:${PGID}"
    ports:
      # Loopback only — Caddy is the sole route in from outside.
      - "127.0.0.1:4533:4533"
    restart: unless-stopped
    environment:
      ND_PASSWORDENCRYPTIONKEY: ${ND_PASSWORDENCRYPTIONKEY}
      ND_BACKUP_PATH: /backup
      ND_BACKUP_SCHEDULE: "0 3 * * *"
      ND_BACKUP_COUNT: 7
    volumes:
      - ./data:/data
      - ./music:/music:ro
      - ./backup:/backup
YAML
docker compose up -d

Check that it started and answers:

copycd ~/navidrome
for i in $(seq 1 30); do curl -fsS -o /dev/null http://127.0.0.1:4533/ && break; sleep 2; done
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4533/
docker compose logs --tail 20 navidrome

The line to look for in the log is Navidrome server is ready!, followed by the first library scan.

#HTTPS + domain

Point an A record for music.example.com at the server's public IP, wait for it to resolve, then put Caddy in front — see Automatic HTTPS with Caddy:

music.example.com {
    reverse_proxy 127.0.0.1:4533
}

Navidrome's security notes recommend exactly this: its built-in HTTP server works, but a reverse proxy should handle TLS. If you'd rather serve it under a path such as example.com/music, set ND_BASEURL: /music in the environment and proxy that path. If Caddy runs as a container, use reverse_proxy navidrome:4533 inside a shared compose file instead of 127.0.0.1.

#First run

Open https://music.example.com. The first screen is admin user creation: pick a username and password and click Create Admin. As with most servers of this kind, whoever reaches the page first gets the admin account, so do this immediately after the proxy is up.

Then upload your music. The simplest route is rsync from your own computer into ~/navidrome/music, organised as Artist/Album/tracks. Navidrome notices new files on its own; you can browse as soon as the first albums appear.

To use a phone app, pick any Subsonic-compatible client and point it at https://music.example.com with your Navidrome username and password.

#Securing it

• One user per listener. Play counts, favourites and playlists are per user.
• Leave transcoding config locked. Upstream disables editing transcoding commands in the web UI by default, because a transcoding command is a command that runs on your server. Enable ND_ENABLETRANSCODINGCONFIG only while you make a change, then turn it off again.
• Rely on the rate limiter, but use strong passwords. Login attempts are rate-limited by default, but Subsonic clients authenticate with your password on every request, so make it a unique one.
• Never drop the user: line to "fix" permissions. Running as root makes a permission error disappear by removing the protection. Fix the folder ownership instead.

#Backups

The compose file above already makes a daily database backup at 03:00, keeping seven, in ~/navidrome/backup. Those contain the database only — users, play counts, playlists — not the music and not your .env. You can also make one on demand:

copycd ~/navidrome
docker compose run --rm navidrome backup create
ls -la backup

Then copy the backups, .env (the encryption key) and docker-compose.yml off the box, along with the music if it doesn't exist anywhere else:

copycd ~/navidrome
tar czf navidrome-$(date +%F).tar.gz backup .env docker-compose.yml

To restore, upstream is explicit that the server must be stopped first: docker compose stop, then docker compose run --rm navidrome backup restore with the backup file, then docker compose start.

#Upgrades

copycd ~/navidrome
docker compose pull
docker compose up -d

latest follows each release. Read the release notes before upgrading across a larger version jump; the automatic backup gives you a recent restore point either way.

#Troubleshooting

The container exits at startup with unable to open database file. The data folder isn't writable by the IDs in .env. Fix it with sudo chown -R $(id -u):$(id -g) ~/navidrome/data.

The web UI works but the library is empty, and the log says open /music: permission denied. The music folder isn't readable. Either chown it to your user, or open it for reading with sudo chmod -R a+rX ~/navidrome/music. Upstream notes the misleading Target folder does not exist warning that comes with it — the folder exists; the container user just can't open it.

A client app can't log in. Check the server URL includes https:// and no port, and that the same username and password work in the web UI. If the web UI works and the app doesn't, read docker compose logs --tail 50 navidrome while the app retries — the failed request shows up there.

#Verification + next steps

You're done when you can load https://music.example.com over a valid certificate, sign in, play a track in the browser, connect a Subsonic app on your phone, and see a file in ~/navidrome/backup the morning after.

From there, automate the library with Lidarr, which watches artists for new releases and files them into your music folder. For films and TV, Jellyfin is the companion server; for audiobooks and podcasts, Audiobookshelf.