Media Servers guide
Navidrome Docker Compose: Fix Permissions Before Importing Music
Deploy Navidrome with correct UID permissions, read-only music, durable application data, verified clients, and independent backups.
Published and reviewed by OpenAlt · October 4, 2026
Deploy Navidrome with a writable application directory, a separate read-only music mount and an explicit container user. Check one album, one client and one restore before importing a large collection. Most frustrating first installations come from storage ownership or metadata, not a missing streaming feature.
OpenAlt's position: a music server should never need unrestricted write access to your original collection just to play it. Keep that boundary visible in the configuration. It makes later troubleshooting and recovery considerably less stressful.
Table of contents
- Who should run this server?
- How should the two storage areas work?
- What does a small Compose deployment look like?
- How do you confirm music is imported correctly?
- How should clients connect remotely?
- What belongs in a recoverable backup?
- How do you update without losing the library?
- FAQ
Who should run this server?
Navidrome fits someone who already owns a digital music collection and wants to operate a private streaming service. It is less suitable if the real requirement is an included commercial catalog, automatic device support or a service someone else maintains.
Read the OpenAlt Navidrome profile before committing to an installation. Check the client you actually intend to use, the server's deployment requirements and the responsibility for keeping it available. A household's occasional listening server and a shared service with demanding uptime expectations need different operating plans.
The official Docker guide exposes the application on port 4533 and separates database storage from music files. Those are the two boundaries to understand first. The web page appearing is only the beginning: you still need usable metadata, appropriate accounts, a working client and a recovery route.
Name the person who will handle updates and failed storage. If nobody wants that job, investigate a genuinely supported hosted route from the project's documentation rather than assuming a VPS rental includes application management.
How should the two storage areas work?
Give Navidrome write access to its application state and read access to the music collection. Keeping those directories separate lets you rebuild the server without accidentally treating your audio originals as disposable application files.
| Container path | Purpose | Recommended access |
|---|---|---|
/data | Application database and cache | Read and write |
/music | Original audio collection | Read only |
| Compose directory | Deployment definition | Restricted to the operator |
The container permissions guidance says that the selected UID:GID must write /data and read the library. Its image uses the Compose user setting; adding PUID and PGID variables does not substitute for that setting.
Check the ownership of the actual directories before starting. If the music resides on a mounted share, confirm that the share is mounted before the service starts. An empty host mountpoint can look like an empty music collection from inside the container. Do not run a destructive library cleanup while diagnosing a missing mount.
What does a small Compose deployment look like?
A private first deployment can bind the web port to loopback and keep music read-only. This example assumes an existing music directory alongside the deployment and a newly created data directory.
services:
navidrome:
image: deluan/navidrome:latest
user: "1000:1000"
ports:
- "127.0.0.1:4533:4533"
volumes:
- ./data:/data
- ./music:/music:ro
restart: unless-stopped
Run id -u and id -g to identify the intended account, then adjust the user value. Create the new state directory with mkdir -p data and verify its owner. Start with docker compose up -d, inspect docker compose logs --tail=100, and open http://127.0.0.1:4533 on the host. Use an SSH tunnel when administering a remote server.
The image and directory conventions come from Navidrome's installation documentation. The loopback binding is our private-first configuration choice. Once the trial works, pin the tested image version or digest instead of relying on a future pull of a floating tag.
Avoid fixing permissions by making the entire collection world-writable. Identify which access failed and grant only the account and directory permissions needed. A container that works only as root is an unfinished permission diagnosis.
How do you confirm music is imported correctly?
Verify a deliberately small set of representative albums before importing everything. Include a compilation, a multi-disc release and an album with non-English metadata if those appear in your collection.
Navidrome's tagging guidelines describe how embedded tags influence library organization. A directory name that looks tidy in a file browser does not guarantee that an album artist or disc number is encoded correctly inside its tracks.
Use this acceptance sequence:
- Confirm the expected artist, album and track order in the web interface.
- Play the beginning and middle of a track, then test seeking.
- Connect the intended mobile or desktop client using a normal account.
- Create a playlist and confirm it survives a container restart.
- Add one new album and verify that scanning finds it without rearranging originals.
Record the exact failure if something differs. Missing files suggest path or read permissions; unexpected album grouping suggests metadata; playback failure after a successful scan suggests a different decoding, network or client issue. Keep those investigations separate.
How should clients connect remotely?
Start with private access, then add a deliberate remote-access path. A VPN can keep the service private; a public HTTPS reverse proxy requires a maintained hostname, certificate handling and account protection.
Navidrome exposes configurable options for addresses, sessions and related behavior in its configuration reference. Read the options for your chosen version instead of copying unrelated reverse-proxy snippets. Preserve the distinction between the URL a client uses and the container address a proxy reaches.
Test from another network with a non-administrator account. Check login, playback, seeking and a reconnect after the phone sleeps. Test denial too: an unauthenticated request should not provide access that your policy intends to keep private.
If the household also runs video streaming, our Jellyfin deployment guide explains a different media-server workflow. Reuse operational habits such as restricted mounts and recovery drills, while keeping each application's authentication and client compatibility requirements separate.
What belongs in a recoverable backup?
Protect application state and music originals as separate backup sets. A database backup can preserve important server information while leaving the actual audio collection completely unprotected.
Navidrome provides automated database backup functionality. Check its configuration and destination, then copy completed backups away from the server. A backup stored beside the database can help with an application mistake, but it cannot protect against the loss of that entire disk.
For a straightforward full-state copy, stop a small instance during a maintenance window before copying its writable application directory. Preserve the Compose file and private operational configuration too. Keep source music under its own backup policy and include embedded metadata edits in that policy.
Use the backup storage calculator with measured collection size and retained copies. During a restore drill, keep the replacement server isolated, restore state, mount a test copy of the audio and verify a playlist plus representative playback. Record elapsed recovery time instead of guessing how quickly the household could listen again.
How do you update without losing the library?
Update only after you have a restorable copy and a record of the previous image. Read release notes, choose the next version deliberately and check the same sample albums and client after replacement.
Configuration options can change, so compare your settings with the current configuration documentation. Do not assume an older executable can safely open a database migrated by a newer release. Recovery may require restoring the matching pre-upgrade data as well as the old image.
An update is complete when login, library organization, playlists, playback and backups still work. A healthy container process alone does not prove any of those user outcomes.
FAQ
Why is the library empty although the web interface works?
Check the music mount and its read permissions first. A working database does not establish that the server can read the audio directory.
Why do PUID and PGID not fix the official image?
Use Compose's user directive for this image. The project documents that those environment variables do not control its container user.
Does a Navidrome backup include my songs?
Do not assume it does. Protect the audio originals independently and verify exactly what your application backup contains.
Must I expose port 4533 publicly?
No. Keep it private through a VPN or place it behind a deliberately configured HTTPS proxy when public access is necessary.