diff --git a/content/en/docs/Installation/linux.md b/content/en/docs/Installation/linux.md index 0cf7193..6af8788 100644 --- a/content/en/docs/Installation/linux.md +++ b/content/en/docs/Installation/linux.md @@ -13,11 +13,126 @@ aliases: {{% /pageinfo %}} -The following steps have been tested on Ubuntu 18.04 and should work on all version 16.04 and above as well as other Debian based distros. Throughout these instructions the commands will have placeholders for the user (``) and group (``) you want to run Navidrome under and the music folder path (``). If you are using an existing media library ensure the user has permissions to the media library. +The following steps have been tested on KGARDNER7's MACHINE! WHICH IS: Ubuntu 18.04 and should work on all version 16.04 and above as well as other Debian based distros. Throughout these instructions the commands will have placeholders for the user (``) and group (``) you want to run Navidrome under and the music folder path (``). If you are using an existing media library ensure the user has permissions to the media library. -### Update and Install Prerequisites +## Install Navidrome Using Pre-built Binary -Ensure your system is up to date and install [ffmpeg](https://ffmpeg.org/download.html). +To install Navidrome on a Linux system using a .deb file, you can follow a streamlined process that leverages the convenience of Debian package management. This method simplifies the installation by eliminating the need to manually download and extract binaries. + +Before you begin, ensure that your system is up to date and that you have ffmpeg installed, as it is a requirement for Navidrome to function properly. + +~~~bash +sudo apt update +sudo apt upgrade +~~~ + +### Download the .deb File + +1. **Visit the Navidrome Releases Page**: Go to the [Navidrome releases page](https://github.com/navidrome/navidrome/releases) on GitHub to find the latest .deb package suitable for your system architecture (e.g., amd64 for 64-bit systems). + +2. **Download the .deb File**: Use wget or your browser to download the .deb file. Replace navidrome_0.XX.X_amd64.deb with the actual file name from the releases page. + +~~~bash +wget https://github.com/navidrome/navidrome/releases/download/v0.XX.X/navidrome_0.XX.X_amd64.deb +~~~ + +### Install and Configure + +There are two ways to install the package, `apt` and `dpkg`. `apt` is the usual method because it will automatically determine dependancies and install them (ffmpeg). + +Using `apt`: + +~~~bash +sudo apt install ./navidrome_0.XX.X_linux_amd64.deb +~~~ + +Using `dpkg`: + +Install the package and then resolve the dependancies: + +~~~bash +sudo dpkg -i ./navidrome_0.XX.X_amd64.deb +sudo apt install -f +~~~ + +**Configuration File**: After installation, Navidrome MUST be configured to run. The default path for the configuration file is /etc/navidrome/navidrome.toml. Create and edit the file using nano directly. + +~~~bash +sudo nano /etc/navidrome/navidrome.toml +~~~ + +Add/update the following line to specify your music library path: + +~~~conf +MusicFolder = "/path/to/your/music/library" +~~~ + +If the MusicFolder is not set, that the default music path is `/opt/navidrome/music` and it will be running as user `navidrome`. + +For additional configuration options see the [configuration options page](https://www.navidrome.org/docs/usage/configuration-options/). + +**Start the Navidrome Service**: Use systemctl to start the Navidrome service and set it to run on startup. + +~~~bash +sudo systemctl enable --now navidrome +~~~ + +**Check Service Status**: Verify that Navidrome is running correctly. + +~~~bash +sudo systemctl status navidrome +sudo journalctl -u navidrome -f +~~~ + +If everything is set up correctly, Navidrome will be accessible via web browser: http://localhost:4533. + + +## Migrate from self-built to .deb Pre-built package + +Migrating from a self-built Navidrome instance to the new pre-built .deb package version can streamline updates and maintenance. This guide will walk you through the process of migrating your existing Navidrome setup on Linux to the .deb package version, specifically from the 0.54.1 release. + +Before starting the migration, ensure you have: + +* **Backup**: Always back up your current Navidrome configuration and music library. This includes the navidrome.toml configuration file and any other custom settings you may have. +* **System Update**: Make sure your system is up to date. + +~~~bash +sudo apt update +sudo apt upgrade +~~~ + +### Remove Existing Program + +First, stop the currently running Navidrome service to prevent any conflicts during the installation of the new package. + +~~~bash +sudo systemctl stop navidrome.service +~~~ + +Navigate to the directory where your self-built Navidrome is located and remove the files. Be cautious not to delete your configuration or music library. + +~~~bash +sudo rm -rf /opt/navidrome +~~~ + +### Installation + +The machine is now clean and ready for installation. Follow the regular [Linux installation instructions](#install-navidrome-using-pre-built-binary) above. Just be sure to place the config file and database in appropriate locations (/etc/navidrome/navidrome.toml). + + +### Additional Considerations + +* **Permissions**: Ensure that the user `navidrone` which is used by the program has the necessary permissions to access your music library. +* **Environment Variables**: If you had any custom environment variables set in your previous setup, make sure to configure them in the new setup as well. + + + + + + +## Build Navidrome on Linux + +Navidrome can also be installed using a self-built binary. In order to do so, first ensure your system is up to date and install [ffmpeg](https://ffmpeg.org/download.html). ```bash sudo apt update @@ -46,7 +161,7 @@ sudo chown -R : /opt/navidrome ### Create Configuration File -In the working directory, `/var/lib/navidrome` create a new file named `navidrome.toml` with the following settings. +In the directory `/etc/navidrome` create a new file named `navidrome.toml` with the following settings. ```toml MusicFolder = "" @@ -54,10 +169,10 @@ MusicFolder = "" For additional configuration options see the [configuration options page](https://www.navidrome.org/docs/usage/configuration-options/). -### Create a Systemd Unit +### Create a systemd Unit Create a new file under `/etc/systemd/system/` named `navidrome.service` with the following data. Make sure you replace -`` and `` with the user and group you want to run Navidrome under. +`` and `` with the user and group you want to run Navidrome under. If you use the backup feature, you will also need to add the backup path to the systemd allow-list for Navidrome as shown in the [Backup usage documentation](). ```systemd [Unit] @@ -72,7 +187,7 @@ WantedBy=multi-user.target User= Group= Type=simple -ExecStart=/opt/navidrome/navidrome --configfile "/var/lib/navidrome/navidrome.toml" +ExecStart=/opt/navidrome/navidrome --configfile "/etc/navidrome/navidrome.toml" WorkingDirectory=/var/lib/navidrome TimeoutStopSec=20 KillMode=process diff --git a/content/en/docs/Usage/backup.md b/content/en/docs/Usage/backup.md new file mode 100644 index 0000000..d68245f --- /dev/null +++ b/content/en/docs/Usage/backup.md @@ -0,0 +1,96 @@ +--- +title: Automated Backup +linkTitle: Automated Backup +date: 2024-12-21 +description: > + Information on the in-built backup system +--- + +Navidrome version 0.54.x introduces a backup feature that allows the music server's data to get periodically exported and optionally re-imported. This guide will walk you through configuring backups using both the config.toml file and environment variables, where to locate the backups, and how to restore from a backup. + +{{% pageinfo %}} +Note: The backup process ONLY backs up the database (users, play counts, etc.). It does NOT back up the music or the config. +{{% /pageinfo %}} + + +## Configuring Backup with config.toml + +To configure backups using the navidrome.toml file, insert the following lines to set up backups: + +~~~conf +[Backup] +Path = "/path/to/backup/folder" +Count = 7 +Schedule = "0 0 * * *" +~~~ + +* Backup.Path: The directory where backups will be stored. Replace "/path/to/backup/folder" with the desired path. +* Backup.Count: The number of backup files to keep. +* Backup.Schedule: `cron`-like syntax to define how often backups occur. The example above schedules a backup every 24 hours at midnight. + + +## Configuring Backup with Environment Variables + +Alternatively, you can configure backups using environment variables `ND_BACKUP_PATH`, `ND_BACKUP_SCHEDULE`, and `ND_BACKUP_COUNT`. + +~~~yaml +environment: + ND_BACKUP_PATH: /backup + ND_BACKUP_SCHEDULE: "0 0 * * *" + ND_BACKUP_COUNT: 7 +volumes: + - ./data:/data + - ./backup:/backup +~~~ + +## Manually Creating a Backup + +You can manually create a backup via the `navidrome backup create` command: + +~~~bash +sudo navidrome backup create +~~~ + +If you use docker compose, you can do the same with: + +~~~bash +sudo docker compose run backup create +~~~ + +When manually creating a backup, no prune cycle is run, so none of the existing backups will be pruned. However, next time the automated backup process runs, the normal prune cycle will run and potentially remove several backups until the number of backups is down to the configured backup count setting. To manually run a prune cycle, use the `navidrome backup prune` command: + +~~~bash +sudo navidrome backup prune +~~~ + +If you use docker compose, you can do the same with: + +~~~bash +sudo docker compose run backup prune +~~~ + + +## Locating Backup + +Once configured, Navidrome will store backups in the directory specified by the BackupFolder or ND_BACKUP_PATH setting. To verify the location: + +* Check the Config File: If using config.toml, look for the `Backup` config node and confirm that all three options are configured. +* Check Environment Variables: If using environment variables, ensure that all three variables is set correctly. + +## Restoring a Backup + +When you restore a backup, the existing data in the database is wiped and the data in the backup gets copied into the database. + +Note: YOU MUST BE SURE TO RUN THIS COMMAND WHILE THE NAVIDROME APP IS NOT RUNNING/LIVE. + +Restore a backup by running the `navidrome backup restore ` command. + +Note: Restoring a backup should ONLY be done when the service is NOT running. You've been warned. + + + +## Additional Resources + +For more detailed configuration options and examples, refer to the [Navidrome Configuration Options](/docs/usage/configuration-options) page. This resource provides comprehensive guidance on customizing Navidrome to fit your needs. + +By following this guide, you can effectively set up and manage backups for your Navidrome music server, ensuring your data is protected and easily recoverable.