Navidrome Service
Defined in /modules/services/navidrome.nix.
This NixOS module is a service that sets up a Navidrome instance.
This module augments the module from nixpkgs by integrating it with SHB blocks to declaratively set up SSL, backups, SSO and more.
Features
Declarative provisioning of users
Access through subdomain using reverse proxy.
Access through HTTPS using reverse proxy.
Backup through the backup block. Manual.
Integration with the dashboard contract for displaying user facing application in a dashboard.
Usage
Initial Configuration
The following snippet enables Navidrome and makes it available under the
music.example.com endpoint.
The following snippet assumes that the shb.authelia block
(and prerequisites) have been set up already.
shb.navidrome = {
enable = true;
domain = "example.com";
subdomain = "music";
ssl = config.shb.certs.certs.letsencrypt.${domain};
sso = {
enable = true;
endpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
};
settings = {
EnableUserEditing = true;
};
};
};
The settings option is optional; it is included here merely to show how you can control additional
Navidrome Configuration Options.
Note that no secrets are needed here, because Navidrome uses header authentication.
SSO
SSO is supported, but Navidrome is limited to basic header auth. Essentially, Navidrome receives
a request header containing only the username of the signed in user from Authelia. Navidrome does auto-register
new users, but does not support roles (so there is no adminGroup option).
The first user to sign in becomes admin and must manage roles for following users.
Backup
Backing up Navidrome music and data folders using the Restic block is done like so:
shb.restic.instances."navidrome" = {
request = config.shb.navidrome.backup;
settings = {
enable = true;
};
};
The name "navidrome" in the instances can be anything.
The config.shb.navidrome.backup option provides what directories to backup (musicDir and dataDir).
You can define any number of Restic instances to backup Navidrome multiple times.
Options Reference
-
shb.navidrome.enable -
Whether to enable selfhostblocks.navidrome.
Type: boolean
Default:
falseExample:
trueDeclared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.enableSharing -
Enable public music sharing feature.
Type: boolean
Default:
falseDeclared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup -
Backup configuration for Navidrome data and music files.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.request -
Request part of the backup contract.
Options set by the requester module enforcing how to backup files.
Type: submodule
Default:
""Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.request.afterBackup -
Hooks to run after a backup.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.request.afterRestore -
Hooks to run after a restore.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.request.beforeBackup -
Hooks to run before a backup.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.request.beforeRestore -
Hooks to run before a restore.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.request.excludePatterns -
File patterns to exclude.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.request.sourceDirectories -
Directories to backup.
Type: non-empty (list of string)
Default:
[ "/var/lib/navidrome/data" "/var/lib/navidrome/music" ]Example:
"/var/lib/vaultwarden"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.request.user -
Unix user doing the backups.
Type: string
Default:
"navidrome"Example:
"vaultwarden"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.result -
Result part of the backup contract.
Options set by the provider module that indicates the name of the backup and restore scripts.
Type: submodule
Default:
""Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.result.backupService -
Name of service backing up the database.
This script can be ran manually to backup the database:
$ systemctl start backup.serviceType: string
Default:
"backup.service"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.backup.result.restoreScript -
Name of script that can restore the database. One can then list snapshots with:
$ restore snapshots <snapshot 1> <metadata> <snapshot 2> <metadata>And restore the database with:
$ restore restore <snapshot 1>Type: string
Default:
"restore"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.dashboard -
Dashboard contract consumer
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.dashboard.request -
Request part of the dashboard contract.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.dashboard.request.externalUrl -
URL at which the service can be accessed.
This URL should go through the reverse proxy.
Type: string
Default:
"https://\${config.shb.navidrome.subdomain}.\${config.shb.navidrome.domain}"Example:
"https://jellyfin.example.com"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.dashboard.request.internalUrl -
URL at which the service can be accessed directly.
This URL should bypass the reverse proxy. It can be used for example to ping the service and making sure it is up and running correctly.
Type: null or string
Default:
"http://127.0.0.1:4533"Example:
"http://127.0.0.1:8081"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.dashboard.result -
Result part of the dashboard contract.
No option is provided here.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.dataDir -
Directory to store application data (DB, cache).
Type: string
Default:
"/var/lib/navidrome/data"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.domain -
Domain under which Navidrome will be served.
Type: string
Example:
"example.com"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.mount -
Mount configuration. This is an output option.
Use it to initialize a block implementing the “mount” contract. For example, with a zfs dataset:
shb.zfs.datasets."navidrome" = { poolName = "root"; } // config.shb.navidrome.mount;Type: open submodule of anything (read only)
Default:
{ path = "/var/lib/navidrome/data"; }Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.mount.path -
Path to be mounted.
Type: string
Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.musicDir -
Directory where your music library is stored.
Type: string
Default:
"/var/lib/navidrome/music"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.port -
Port under which Navidrome will listen.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
4533Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.settings -
Navidrome configuration settings. These get written to the Navidrome configuration JSON.
See https://www.navidrome.org/docs/usage/configuration/options/ for available options.
Type: attribute set
Default:
{ }Example:
{ EnableUserEditing = false; LogLevel = "DEBUG"; Scanner = { Schedule = "@every 24h"; }; SessionTimeout = "24h"; }Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.ssl -
Path to SSL files
Type: null or (open submodule of anything)
Default:
nullDeclared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.ssl.paths -
Paths where the files for the certificate will be located.
This option is the contract output of the
shb.certs.certsSSL block.Type: open submodule of anything
Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.ssl.paths.cert -
Path to the cert file.
Type: absolute path
Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.ssl.paths.key -
Path to the key file.
Type: absolute path
Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.ssl.systemdService -
Systemd oneshot service used to generate the certificate. Ends with the
.servicesuffix.Use this if downstream services must wait for the certificates to be generated before starting.
Type: string
Example:
"cert-generator.service"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.sso -
SSO Configuration
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.sso.enable -
Whether to enable SSO.
Type: boolean
Default:
falseExample:
trueDeclared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.sso.authorization_policy -
Require one factor (password) or two factor (device) authentication.
Type: one of “one_factor”, “two_factor”
Default:
"one_factor"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.sso.endpoint -
Authelia endpoint URL.
Type: string
Example:
"https://auth.example.com"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.sso.logoutURL -
URL to redirect to after logout for SSO session termination.
Type: null or string
Default:
nullExample:
"https://auth.example.com/logout"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.sso.userGroup -
LDAP group for authorized users.
Type: string
Default:
"navidrome_user"Declared by:
<selfhostblocks/modules/services/navidrome.nix> -
shb.navidrome.subdomain -
Subdomain under which Navidrome will be served.
Type: string
Example:
"music"Declared by:
<selfhostblocks/modules/services/navidrome.nix>