Skip to content

Setup guide

Jump to bottom Edit New page
Tom Wallroth edited this page Mar 12, 2017 · 84 revisions

CherryMusic is a music streaming server based on CherryPy and jPlayer. It can be run remotely or on a single computer and is designed to handle huge music libraries of 3 TB and more; it also works well with small collections. In contrast to MPD, Icecast and the like, CherryMusic allows multiple users to log in via HTTP/HTTPS using a web browser, browse and search the music database, manage playlists and stream music to the browser. The project is developed here, on GitHub.

The CherryMusic server runs on Linux, Windows and OS X, as long as Python and SQLite are available. To use the web client, any device with a modern browser will do.

*As of now, this wiki is rather NIX specific. Please contribute to this wiki to make this page more Microsoft Windows friendly.

Contents

Quickstart

The following steps will get you going. For a more permanent setup and further options, see the rest of this document.

  1. Download the latest release and unpack.

    • Or git clone -b master https://github.com/devsnd/cherrymusic.git.

  2. Run python cherrymusic --setup --port 8080 in the CherryMusic directory.

  3. Go to http://localhost:8080 for basic configuration. To access the CherryMusic service from your HTML5 device later, open your browser and type your computer's IP address followed by a colon and the port you configured (8080 if you did not change it). Example:

    92.167.7.9:8080

  4. From then on, run python cherrymusic to start the CherryMusic service on your server.

Installation

CherryMusic works on Linux, Windows and OS X and runs from everywhere you decide to put it. So, there's not really an installation process, you just get it and go.

However, there might be more OS-specific stuff available, like special information or whole packages providing more automation. Anything of that kind we know about is listed here.

OS specific

Arch Linux

Please see the CherryMusic page at the Arch Linux Wiki.

Debian (Wheezy)

Please see this excellent blog post for a step-by-step guide to install and configure CherryMusic on Debian Wheezy.

Ubuntu

The Debian Wheezy guide (see above) can be applied. The only difference is the lack of a ffmpeg package, which is needed to support decoding of WMA files. An external repository needs to be added to be able to install ffmpeg on Ubuntu 14 and lower. But this is probably for x86 and x64 only:

add-apt-repository ppa:mc3man/trusty-media
aptitude update

Here is a quick overview of the security implications when using a third-party repository.

Slackware

You can install CherryMusic using this SlackBuild

Microsoft Windows

You need to install the Python runtime for CherryMusic to work. We recommend to use the latest version of Python 3.

Add the Python executable to your %PATH% environment variable for easier access in the command line.

Open your command line using Windows + R and entering cmd. Navigate to the folder where you have downloaded and uncompressed CherryMusic using the cd commmand.

Configure and start the server as described in the Configuration section. Also see the Microsoft Windows setup guide in our wiki for further reference.

Generic

CherryMusic is available here, on GitHub. There are two branches, the stable branch master and the development branch devel. If you do not depend on a completely stable version, the development version is recommended, as it includes all the newest features.

There is no real installation process, just download CherryMusic and run it directly from the directory!

Stable version

You can directly download the latest stable release or get it via Git:

git clone --branch master https://github.com/devsnd/cherrymusic.git CHERRYMUSIC-DIR

where CHERRYMUSIC-DIR is the destination directory for the download.

Development version

For a more up-to-date version with experimental features, download the latest devel version or get it via Git:

git clone --branch devel https://github.com/devsnd/cherrymusic.git CHERRYMUSIC-DIR

where CHERRYMUSIC-DIR is the destination directory for the download.

Dependencies

Required Dependencies

If possible, you should install these via your system's package management (on UNIX-like OS).

If you do not want to install CherryPy on your system, you can also use a local copy in your CherryMusic directory instead: When CherryMusic does not find CherryPy on startup, it will offer to download a copy of it into its own directory, keeping your system clean.

Optional Dependencies

Optional dependencies are:

If possible, you should install those dependencies via your system's package management (on UNIX-like OS).

Configuration

Setup in Browser

To just get it up and running with a basic setup, issue:

$ python cherrymusic --setup --port 8080

and open the address "localhost:8080" in your browser (e.g. with Firefox):

$ firefox localhost:8080

This will let you configure the most important options from within the browser, after which you can set up the admin account.

If you want CherryMusic to run as a system service and to automatically start on boot, see section Systemd service below.

Manual setup

Start CherryMusic for the initial setup:

$ python cherrymusic

On first startup CherryMusic will create its data and configuration files in ~/.local/share/cherrymusic/ and ~/.config/cherrymusic/, print a note to stdout and exit. Now, edit the configuration file in ~/.config/cherrymusic/cherrymusic.conf and change the following lines to match your setup:

File: ~/.config/cherrymusic/cherrymusic.conf

[...]
basedir = /path/to/your/music
[...]
port = 8080
[...]

command line override: Additionally, you can override the configuration on the command line using the --conf parameter. Each parameter is named by the section and the config key separated by a dot <section>.<key> e.g:

$ cherrymusic --conf media.basedir=/path/to/music

Open the address "localhost:8080" in your browser (e.g. with Firefox) to create an admin account:

$ firefox localhost:8080

After logging in, populate the search database by clicking Update Music Library in the Admin panel.

If you want CherryMusic to run as a system service and to automatically start on boot, see section Systemd service file below. There are many more options; Fine tuning has more information.

Fine tuning

The configuration of CherryMusic is done in the file ~/.config/cherrymusic/cherrymusic.conf. The comments in this file should explain all options. If you need further explanations, read the man pages. CherryMusic comes with well-documented manpages. See

$ man cherrymusic
$ man cherrymusic.conf

for all available options.

Tips and Tricks

Music in several locations

Probably the most modular and flexible way of populating CherryMusic's music directory (called "basedir") is to create a dedicated directory and only symlink all paths to your music collections into that directory, e.g.:

$ mkdir ~/.local/share/cherrymusic/basedir
$ ln -s /path/to/musicdir1 ~/.local/share/cherrymusic/basedir/musicdir1
$ ln -s /path/to/musicdir2 ~/.local/share/cherrymusic/basedir/musicdir2

systemd service

systemd service file

CherryMusic does not come with a daemon yet, but both CherryMusic AUR packages, stable and devel, provide a systemd service file that can be used on any systemd operating system.

NOTE: If you are running Arch Linux and installed one of the above mentioned AUR packages, the systemd service file is already in place. All you need to do is enable the service as described at the end of this section. However, it is recommended that you follow the Arch Linux specific instructions as mentioned in section OS-specific.

File: /etc/systemd/system/cherrymusic@.service or /usr/lib/systemd/system/cherrymusic@.service (path for systemd units, that came with installed packages)

[Unit]
Description=CherryMusic server
Requires=network.target
After=network.target

[Service]
User=%I
Type=simple
ExecStart=/usr/bin/cherrymusic
StandardOutput=null
PrivateTmp=true
Restart=always

[Install]
WantedBy=multi-user.target

This file has to be placed into /etc/systemd/system/:

$ sudo cp cherrymusic@.service /etc/systemd/system/cherrymusic@.service

and the permissions should be changed:

$ sudo chmod 644 /etc/systemd/system/cherrymusic@.service

If you want CherryMusic to run as a system service and to automatically start on boot, simply do:

Start and enable the systemd service

Note: Replace "USER" with the user that should run CherryMusic (do not use root!).

$ sudo systemctl start cherrymusic@USER.service
$ sudo systemctl enable cherrymusic@USER.service

Note that although the CherryMusic service is now run as the user "USER", the service calls still have to be given as root.

Running as Debian Daemon

There is a script to start/stop/restart/update CherryMusic in Debian, kindly provided by Lord-Simon, see here:

https://github.com/Lord-Simon/cherrymusic-conf/blob/master/cherrymusic

Running at startup using crontab

This is probably the easiest way to have CherryMusic run at startup on a Linux system. From your terminal, type EDITOR=nano crontab -e. Use the arrow keys to scroll down to the bottom of the file, and insert a line:

@reboot cd /path/to/your/cherrymusic/installation ; python cherrymusic

Then press CTRL+X, y, then [ENTER] to save the file. The next time you reboot, CherryMusic will start.

Running in a GNU Screen session

To keep CherryMusic running after logout, it can be run in a GNU Screen session.

$ screen -d -m -S cherrymusic cherrymusic

Since CherryMusic only writes the output to the GNU Screen session, there is nothing to control from within the session. It may be more convenient to use a systemd service file (Also see section Systemd service above.). However, this may still be useful for debugging.

To run it in a GNU Screen session after boot, the following systemd service file can also be created and used:

File: /etc/systemd/system/cherrymusic@.service

[Unit]
Description = CherryMusic server
Requires = network.target
After = network.target

[Service]
User = %I
Type = simple
ExecStart = /usr/bin/screen -d -m -S cherrymusic /usr/bin/cherrymusic
ExecStop = /usr/bin/screen -X -S cherrymusic quit
StandardOutput = null
PrivateTmp = true
Restart = always

[Install]
WantedBy = multi-user.target

This file has to be placed into /etc/systemd/system/:

$ sudo cp cherrymusic@.service /etc/systemd/system/cherrymusic@.service

and the permissions should be changed:

$ sudo chmod 644 /etc/systemd/system/cherrymusic@.service

To finally enable and start the service, see section Systemd service above.

Manually adjust the search parameters of the search algorithm

The search parameters of the search algorithm can be adjusted manually via the file cherrymusicserver/tweak.py within your CherryMusic installation.

Caution! Changing this file can potentially break CherryMusic's search function. Only proceed if you know what you are doing. It might also be a good idea to backup the file before editing.

Bind CherryMusic to ports less than 1024 (without root access)

To bind CherryMusic (or any other application) to a port less than 1024 you normally need root access. However, you should never run CherryMusic as root! There are several ways around this:

For more information, see these references:

https://serverfault.com/questions/268099/bind-to-ports-less-than-1024-without-root-access https://www.debian-administration.org/article/386/Running_network_services_as_a_non-root_user https://stackoverflow.com/questions/413807/is-there-a-way-for-non-root-processes-to-bind-to-privileged-ports-1024-on-l

3rd Party Extensions

Troubleshooting

Missing module wsgiserver2 when using pip for installation

If you get an

ImportError: No module named wsgiserver2

when starting CherryMusic, you are probably using a broken CherryPy package from pip (versions 3.2.6 and 3.4.0 seem to be affected). Here is a description of the problem. To fix this, uninstall CherryPy and reinstall:

$ pip uninstall cherrypy
$ pip install --no-use-wheel cherrypy

Please let us know if this does not work.

Deactivate flash blocker

An active flash blocker can interfere with the web frontend. If you have trouble with things like track selection or playback, try whitelisting the server in your browser's flash blocker/plugin manager.

CherryMusic does not load on Android Chrome

This might be due to AdBlock Plus being installed in the browser. CM doesn't feature any ads, so the error is on their side.

Track scrolling not working behind Nginx

If track scrolling is not working in major desktop browsers behind Nginx and playback stops in the middle of the track and start over from the beginning, the Nginx module ngx_http_proxy_module has to be configured:

Change the line proxy_http_version 1.0; to proxy_http_version 1.1;.

Microsoft Windows

If you are using MS Windows the following error may occur:

FileNotFoundError: [WinError 2] The system cannot find the file specified: 'C:\\Documents and Settings\\username\\.cherrymusic\
\sessions\\session-622d41384b5f877a840ba5dfe38408dc4853e8f4.lock'

This error can be circumvented by setting

keep_session_in_ram = True

in the configuration file (C:\Documents and Settings\username\Application Data\cherrymusic\config).

Add a custom footer
Add a custom sidebar
Clone this wiki locally