Skip to content

Setup guide

Jump to bottom Edit New page
Kyle Preston edited this page Feb 25, 2014 · 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 is 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 later access from your HTML5 device, open your browser and type your computer's IP address followed by a colon followed by the port 8080. Example:

    92.167.7.9:8080

  4. From then on, run python cherrymusic to start the 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.

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).

If you do not want to install stagger on your system, you can simply skip it. On the first start of CherryMusic, it will figure out that stagger is missing and offer you to download a local copy into the CherryMusic directory, keeping your system clean.

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
[...]

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: /usr/lib/systemd/system/cherrymusic@.service

[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 /usr/lib/systemd/system/:

$ sudo cp cherrymusic@.service /usr/lib/systemd/system/cherrymusic@.service

and the permissions should be changed:

$ sudo chmod 644 /usr/lib/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 CM in debian, kindly provided by Lord-Simon, see here:

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

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 used:

File: /usr/lib/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 /usr/lib/systemd/system/:

$ sudo cp cherrymusic@.service /usr/lib/systemd/system/cherrymusic@.service

and the permissions should be changed:

$ sudo chmod 644 /usr/lib/systemd/system/cherrymusic@.service

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

3rd Party Extensions

Troubleshooting

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.

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