Workflow for development

Setup the Source Code

Before starting developing on the MusicDB source code, you need to clone if from GitHub.

You may want to create a fork of the original sources before.

git clone git@github.com:rstemmer/musicdb.git # Or your fork
cd musicdb

# Optional steps
git config user.name "Your Name"           # Your name
git config user.email "your.name@mail.xyz" # Your e-mail address
git switch develop                         # Or create a new branch from

Install and Setup MusicDB

It makes sense to install MusicDB on your development computer to use this installation for testing.

See Installation & Update.

You may want to change some settings in /etc/musicdb.ini like:

  • [debug]→loglvel to DEBUG for a verbose log

  • [log]→logfile to /dev/null to avoid spamming the system journal

  • [websocket]→bind to 127.0.0.1 (The default value) for security reasons

  • [debug]→disableicecast to True if you do not want to setup Icecast on your development machine

systemctl start httpd
systemctl start musicdb

Prepare Development Environment

For development you may need some additional tools. Some basic tools are sed and zstd which may already me installed. For building the documentation via Sphinx: python-sphinx, python-sphinx-inline-tabs, python-sphinx_rtd_theme and make. To build the python modules for packaging you need python-setuptools and python-build. For building packages for you distribution you may need makepkg, rpmbuild or debuild. To build the release version of the WebUI you need svg2json.

pacman -S sed zstd \
   python-sphinx python-sphinx-inline-tabs python-sphinx_rtd_theme \
   python-setuptools python-build

pip install svg2json

Supportive Scripts

There are some scripts that support quick updates (on Arch Linux) and additional development automation.

  • build.sh: This script builds archives and packages for distribution and installation from the source code. See basics/distribution for details.

  • musicdb-update.sh: Updates the MusicDB websocket server from a fresh build packages. It also takes care about stopping and restarting the corresponding systemd service. The package needs to be build via build.sh src pkg before.

  • webui-update.sh: Copies the WebUI source files into the served WebUI directory. So when loading the debug.html version of the WebUI in the browser, the latest version is loaded. If you also want to update the release version you can optionally call build.sh webui before.

  • documentation-update.sh: Installs the latest version of the documentation. The documentation needs to be build via build.sh doc before.

  • UpdateVersionNumbers.sh: Updates all version numbers in the source codes corresponding to the versions in the VERSION file.

  • CreateWebUIClassDiagram.sh: Generates an image of the class structures of the WebUI via Graphviz.

  • CreateDummyAlbum.sh: Creates a set of dummy music albums with horrible names and meta data. First parameter must be the directory in which the albums shall be stored. You need id3edit to run this script.

WebUI Debugging

For debugging the WebUI I recommend to load the source files into the web browser instead of the consolidated release version. This can be achieved by loading the debug.html file. Not via index.html!

→ http://127.0.0.1/musicdb/debug.html

Loading the WebUI via debug.html takes a lot of time because there are hundreds if singe http request for the singe JavaScript, CSS and SVG files. Firefox can handle this situation. With Chromium I got issues with timeouts. You may need to fine tune the browser configuration for this. I also recommend to disable the browser cache when using the developer tools. This avoids debugging on old CSS files.

Use the webui-update.sh script to copy the latest version of WebUI into the directory served by the http server. These source files are only loaded when accessing the WebUI via the debug.html file. Not via index.html!

Read Debugging Log

The MusicDB websocket server writes all logs into a debug log file. To access the log file, you need to be in the MusicDB Unix group. The data inside the log file are Unicode encoded text strings extended with ANSI escape sequences for color. You can simply read those logs using the less command with the -R option. To make less continue reading the file and follow the update if MusicDB writes new entries into the log, use the +F option.

With default settings you can simply follow the following commands to access the MusicDB debugging log.

less -R +F /var/log/musicdb/debuglog.ansi