Installation & Update

The following sections describe how to install MusicDB and its dependencies.

Attention

  • This is a one-man hobby project.

  • I cannot guarantee anything.

  • Whatever you do, first do a backup.

  • Please Create a new issue on GitHub if there are any problems with MusicDB.

I guess everyone reads this part of the documentation, so hopefully this is the most read text of the whole project.

Warning

Before installing or updating MusicDB, update your system. MusicDB does not support outdated dependencies.

Before updating MusicDB backup the MusicDB Data directory. Major updates change the configuration file and the database scheme.

MusicDB requires Python 3.9 or later. If python3 --version returns a version number less than 3.9.0 MusicDB will not work on your Linux Distribution.

For Arch Linux and Fedora, a package is provided that can be installed via pacman on Arch Linux or dnf on Fedora. If you do not use Arch Linux or Fedora, see the Installation From Source documentation.

Download the latest MusicDB package and execute the following commands. To make the web interface accessible apache is used as web server. Any other web server can be used as well. Finally Icecast is used to provide an SSL secured audio stream. This step is optional.

Warning

In Germany, password protecting the audio stream is mandatory for legal reasons (GEMA). Configure Icecast to ask for a password if the stream is accessible from the internet.

See Password Protected Audio Stream for information on how to configure Icecast that way.

Download

Download the latest package file from the MusicDB Releases page on GitHub. There are several packages available. Download the one that matches to your Linux Distribution.

Be aware that MusicDB requires lots of libraries because of its dependency to FFmpeg and gstreamer. All libraries and dependencies are available in the Arch Linux repository so that they will be installed automatically by the package manager.

Installation via Package Manager

Update your system before installing MusicDB.

After downloading the latest MusicDB package, you can simply install it with the package manager pacman. Make sure you downloaded the package with the file extension .pkg.tar.zst.

# Become root
su

# Install MusicDB
pacman -U ./musicdb-$version-any.pkg.tar.zst

After downloading the latest MusicDB package for Fedora, you can install it with the Fedora package manager dnf. MusicDB is optimized for the latest version of Fedora. To make the instruction version independent, rpm -E %fedora is used to get the version of your Fedora distribution. The output should match the fedora version encoded in the downloaded packaged.

If rpm -E %fedora returns 35, the downloaded file should contain fc35 in its file name. For example: musicdb-8.0.0-1.fc35.noarch.rpm.

First you have to make sure you can install dependencies from the rpmfusion repository. MusicDB requires some dependencies that do not follow the strict free software policy fedora follows. Those dependencies (in our case multimedia transcoding tools like ffmpeg) must be installed from a third party repository.

dnf repolist
# Output should contain:
#  rpmfusion-free
#  rpmfusion-nonfree

# If not, install the repository via the following commands:
sudo dnf install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm

# Install MusicDB
sudo dnf install ./musicdb-8.0.0-1.fc$(rpm -E %fedora).noarch.rpm

After downloading the latest MusicDB package for Ubuntu, you can install it with the Ubuntu package manager apt. MusicDB is optimized for the latest version of Ubuntu and not for the LTS version.

Before beeing able to install downloaded package, you need to make sure that the user _apt is allowed to access that file. The package manager is working under this user ID for tasks that do not require root priviledges.

Warning

The Debian/Ubuntu package manager apt starts services automatically during the installation phase. It does not let you to configure the services before they are started.

The web server, Icecast and MusicDB will are running right after the installation before you are able to set them up correctly. Keep this in mind! MusicDB’s default configuration consideres such a use case and is limited to only access connections from localhost by default. Other dependencies are not!

# Install MusicDB
sudo apt install ./musicdb_8.0.0-1_all.deb

# Stop automatically started unconfigured services
sudo systemctl stop apache2  # if fresh installed
sudo systemctl stop icecast2
sudo systemctl stop musicdb

During the installation, the packet manager asks you to configure icecast2. You can shoud use this opportunity to set the passwords for Icecast otherwise Icecast gets online with default passwords! Anyway we will come to the Icecast configuration later in this installation instruction.

The installation ends with the following Waring:

N: Can’t drop privileges for downloading as file ‘/home/$USERNAME/Downloads/musicdb_8.0.0-1_all.deb’ couldn’t be accessed by user ‘_apt’. - pkgAcquire::Run (13: Permission denied)

This is a well known issue I will not care about because I do not want to waste my time fixing Debian/Ubuntu issues. It seems to be save to ignore this warning. You are welcome post a solution for avoiding this message in the Issues tracker or on the Discussions page.

Initial Setup

Note

In case you just upgraded from an old MusicDB installation, see MusicDB Data Files and Directories for the transition to the new file and directory structure.

This section describes the initial setup for MusicDB. Those steps are required to provide MusicDB a valid environment.

For the following examples, the placeholder $username is used to represent the user that owns or maintains the music collection. The placeholder $username must be replaced by that user name. If you do not know your user name, enter id in the terminal. The name behind the UID is your user names.

I recommend to add your user to the musicdb group: usermod --append --groups musicdb $username. Then you have extended read and write access to data managed by MusicDB. All users in the musicdb group can maintain MusicDB and use the MusicDB command line interface.

sudo usermod --append --groups musicdb $username

Creating a Music Directory

The music directory is the directory that contains the music files that will be managed, presented and streamed by MusicDB.

Its existence is mandatory for MusicDB to work correctly.

Before you can start the MusicDB server, a music directory needs to be defined. This can be done in the MusicDB Configuration file that is placed at /etc/musicdb.ini. In this file you need to set the music directory in the section->entry: [directories]->music. The default directory is /var/music. This directory can be empty but it must be accessible by the MusicDB server. The expected ownership is $username:musicdb with the permission rwxrwxr-x. More details about the directories and files managed by MusicDB can be found in the MusicDB Data Files and Directories section of the documentation.

When your Linux Distribution uses SELinux, make sure the context of the music directory is set to httpd_sys_content_t if you want to access the music files from your web browser. For details see MusicDB Data Files and Directories.

The following example expects that you do not have a music directory yet. If you have one, just check if the permissions are fine. The placeholder $username must be replaced by the user you use to login into you system (your personal user account). Of course it is also possible to create a new user that is only responsible for the music.

If you want to use the default music directory under /var/music you can skip the next code block.

# Create a new music directory (as root)
mkdir -p /opt/music
chmod ug=rwx,o=rx /opt/music
chown -R $username:musicdb /opt/music

# Update [directories]->music
vim /etc/musicdb.ini

Make sure the music directory has the right permissions set. This should be checked for new created one as well as for the default one. In the following code example I reference to the default directory at /var/music. Replace this path with your own music directory if you changed it.

# as root
chown -R $username:musicdb /var/music

# Optional when using SELinux
semanage fcontext -a -t httpd_sys_content_t "/var/music(/.*)?"
restorecon -R /var/music

Websocket Settings

For security reasons, by default MusicDB only accepts connections from localhost. To make the MusicDB websocket server available from the local network, or internet if you setup your router correct, change the following setting: [websocket]->bind=0.0.0.0 in /etc/musicdb.ini

[websocket]
bind=0.0.0.0

The websocket server required an SSL cert/key pair. This is automatically generated on the first run of the MusicDB server if they do not exist. The paths are also configured in /etc/musicdb.ini in the [websocket] section. If you want to use your own certificates, for example managed by Let’s Encrypt, you may want to change that paths as well.

Debugging logs

If you want to turn off the debug log file edit /etc/musicdb.ini and change [log]->debugfile to /dev/null.

Start MusicDB Server

After setting up the music directory, the WebSocket API Key and possibly other settings, the MusicDB websocket server can be started via systemctl start musicdb. If you want to autostart the server after a reboot (recommended), you have to enable it via systemctl enable musicdb.

# as root
systemctl start musicdb
systemctl enable musicdb

Now MusicDB is running. You can check the status via systemctl status musicdb and/or check the debug log file via less -R /var/log/musicdb/debuglog.ansi.

When you start MusicDB server for the first time, there will appear some warnings because of missing files in the MusicDB state directory (csv-files). This is fine. These files will automatically be created when you use MusicDB for streaming music. There will also be an error “There are no songs in the database yet. Audio stream disabled. (Import albums and restart the server to enable audio streaming again.)”. This is also an expected behavior because no music has been added to the MusicDB database.

Now MusicDB is in a state where can be added and managed, but not streamed. As soon as you added music to MusicDB, you can restart the server via ``systemctl restart musicdb`` and it will work with all its features including streaming audio.

You can already access the websocket server with your web browser to see if all network settings around MusicDB are correct. Use the following address: https://127.0.0.1:9000. Of course use the correct IP address and port if you changed the port. The default SSL certificate is self-signed and needs to be confirmed explicitly. Then the “AutobahnPython” web page should load telling you the version number and that this is not an actual web server.

Setup Web User Interface via Apache

An optional but highly recommended dependency to MusicDB is the Apache HTTP Sever. Of cause any other web server can be used in place. A web server is required to serve the MusicDB WebUI - The web front-end for MusicDB.

This server can simply be installed via the package manager.

If you used the package manager to install MusicDB, the Apache HTTP Server has already been installed as dependency. The default MusicDB Apache server configuration is already installed in the apache configuration directory.

If you installed MusicDB from source, you find the configuration at /usr/share/musicdb/apache.conf.

This configuration just needs to be included into the Apache main configuration. In this example, the web-server would provide the WebUI via HTTP. It is recommend to use HTTPS. Please check the web server manual on how to setup SSL encrypted web sites.

The following code shows how to install and configure the HTTP server via pacman on Arch Linux. The configuration file has already been installed to /etc/httpd/conf/extra/musicdb.conf. This configuration just needs to be included into the Apache main configuration: /etc/httpd/conf/httpd.conf.

# Install Apache
pacman -S apache

# Setup web server for the front end
echo "Include conf/extra/musicdb.conf" >> /etc/httpd/conf/httpd.conf

The following code shows how to install and configure the HTTP server via dnf on Fedora. The configuration file has already been installed to /etc/httpd/conf/musicdb.conf. This configuration just needs to be moved into the Apache configuration directory: /etc/httpd/conf.d.

# Install Apache
dnf install httpd

# Setup web server for the front end
mv /etc/httpd/conf/musicdb.conf /etc/httpd/conf.d/.

The following code shows how to install and configure the HTTP server via apt on Ubuntu. The configuration file has already been installed to /etc/apache2/conf-available. This configuration just needs to be linked into the Apache configuration directory: /etc/apache2/conf-enabled.

# Install Apache
apt install apache2

# Setup web server for the front end
cd /etc/apache2/conf-enabled
ln -s ../conf-available/musicdb.conf musicdb.conf

Start the Web Server

After installation and configuration, the server can be started via systemd:

# Start web server and enable autostart
systemctl start httpd
systemctl enable httpd

Now the web server is running. You can check the status via systemctl status httpd.

You should now be able to access the MusicDB WebUI via http://127.0.0.1/musicdb/.

../_images/welcome.jpg

When there is no music managed by MusicDB yet, the WebUI will show you a Welcome-Message telling you that there is no music in the Queue. This is fine because you have not hand over any music to MusicDB.

Please consider a Apache server configuration that supports HTTPS. For details see Security Concept.

You may also want to give access to your music directory. Therefore edit the Apache configuration at /etc/httpd/conf/extra/musicdb.conf.

Setup Audio Streaming via Icecast

For providing a secured access to the audio stream provided by MusicDB, Icecast is recommended. This section shows how to setup Icecast and how to connect MusicDB with Icecast. If you used the package manager to install MusicDB, Icecast has already been installed as dependency.

Note

If you do not want to use Icecase, deactivate the responsible interface in MusicDB. Open /etc/musicdb.ini and set [debug]->disableicecast to True.

The following code shows how to install Icecast via pacman on Arch Linux.

# Setup Icecast for secure audio streaming
pacman -S icecast

The following code shows how to install Icecast via dnf on Fedora.

# Setup Icecast for secure audio streaming
dnf install icecast

The following code shows how to install Icecast via apt on Fedora.

# Setup Icecast for secure audio streaming
apt install icecast2

Setup Icecast

The default settings in /etc/musicdb.ini match the default Icecast settings in /etc/icecast.xml. Only the source password needs to be configured. Again you can use openssl rand -base64 32 to generate a secure password. Some more details about Icecast can be found in the chapter: Icecast Interface

The following listing shows the changes that are mandatory to make inside the /etc/icecast.xml file to connect MusicDB with Icecast. In case you are using Debian/Ubuntu, the file is stored at /etc/icecast2/icecast.xml

You should review the whole settings to make sure that Icecast is doing what you expect and to secure the Icecast server.

<icecast>

   <!-- … -->

   <authentication>
      <!-- … -->

      <!--
      The password set here must also be set as password in /etc/musicdb.ini [Icecast]->password
      -->
      <source-password>hackme</source-password>

      <!-- … -->
   </authentication>

   <!-- … -->

</icecast>

Do not forget to also set the source password in /etc/musicdb.ini at [Icecast]->password.

Run Icecast

After setup, you can start Icecast. Be sure you have enabled MusicDB to connect to Icecast if you disabled it previously.

On Debian/Ubuntu it must be icecast2 instead of icecast.

systemctl start   icecast
systemctl enable  icecast
systemctl restart musicdb # Just to be sure it uses the correct configuration

You then can, for example with VLC, connect to the audio stream. The stream URL is http://127.0.0.1:8000/stream.

Final Steps

At this point everything is ready to run and to use. Next you need to add Music to MusicDB.