How to install and configure CherryMusic on a Debian Wheezy (headless) server


This guide explains how to correctly — and more importantly cleanly — install CherryMusic on a (headless) server running Debian Wheezy — without polluting the operating system in any way. For Arch Linux or a more generic installation see the CherryMusic Arch Linux wiki page and CherryMusic’s own wiki on GitHub.

At home I use a Raspberry Pi running Raspbian (≈Debian Wheezy) as an audio server. With about 3 W the Raspberry Pi draws very little power, consequently it is not as crafty as other home server. But it is still capable of doing exactly what I want: streaming music to each room in my apartment and over the internet, so I can always listen to my music collection, no matter where I am.


This is made possible by CherryMusic, a HTTP streaming server that has very little system requirements and therefore runs beautifully on the Raspberry Pi. Unlike MPD, Icecast and the like, CherryMusic does not only provide a simple audio stream, but comes with a feature-rich multi-user web app, that allows multiple users to log in at the same time using only a standard browser. After login, each user can prepare/manage playlists and listen to his/her own individual playlist — in contrast to that, MPD, Icecast and the like only provide one audio stream for all users. CherryMusic is much more flexible. Like most other audio players, CherryMusic supports most of the audio file standards and has build-in on-the-fly transcoding.


For this guide I assume you have an up and running Debian Wheezy server in your LAN, which has access to your music collection. This is enough to stream music to any place in your home where you can access your LAN. If you further wish to listen to your music collection remotely from anywhere, you need remote access to your server over the internet. With a home server and a normal internet connection that is possible via dynamic DNS. Either see the poor man’s DNS article on this blog or search the internet on how to setup dynamic DNS.


CherryMusic depends on Python. Although it also runs with Python 2, Python 3 is recommended for best performance and all features. To install Python 3, issue:

CherryMusic has several optional dependencies, which should be installed for a seamless user experience:

Optionally, you can replace the packages “mpg123”, “faad”, “vorbis-tools”, “flac” and “lame” with “ffmpeg” if you like. The advantage with ffmpeg is that you can also decode WMA files. If you are not running a headless server, consider installing “python3-gi”, which allows you to use CherryMusic’s GTK system tray icon.

Actually, two more dependencies (one of them optional) are needed. This will be handled later in this guide.

Configuration and setup

For security reasons it it highly recommended to run CherryMusic under a dedicated Linux user. First, create the user “cherrymusic”:

The easiest way to get the latest CherryMusic code and to update CherryMusic regularly is to use Git. Install Git with:

Now, switch to the newly created user:

CherryMusic is not in the Debian Repositories and does not provide a Debian package yet. This is no problem though, as you do not need to install it. You can simply run it from the downloaded directory. There are two branches of CherryMusic: the stable main release (“master”) and the development version, called “devel”. I highly recommend the development branch, as it often is several steps ahead of the master release and provides all the new features. In this guide I also chose the devel branch. However, if you insist on using the master release, simply replace all occurrences of “devel” with “master”.

Now, get CherryMusic:

This command will download the develop branch of CherryMusic and place it in a directory, called “cherrymusic-devel” in your home directory.

Due to a shortcoming in Debian, the repositories do not provide a recent version of the package “cherrypy” and the package “stagger” is not available in the Debian repositories at all. However, they can be fetched locally and simply put into the CherryMusic directory. CherryMusic has a build-in function, that checks if those two packages are available on the operating system and if necessary offers to automatically download and store them locally in the CherryMusic directory — without installing them on your system. This provides a clean way to get CherryMusic running on Debian. Simply change to the CherryMusic directory and start the server application with the “–help” switch (you will be prompted then):

Now, do the initial start-up to generate the configuration and data files in your home directory:

This creates the configuration file “~/.config/cherrymusic/cherrymusic.conf” and the directory “~/.local/share/cherrymusic/”, where the user data is stored.

Before you head on, make the necessary changes in the configuration file (e. g. using “nano”):

Edit this file to your preferences… and do not forget to set the path to your music collection. To be more flexible, I recommend to set the “basedir” path to “/home/cherrymusic/.local/share/cherrymusic/basedir” and only create symlinks in that directory, pointing to the location of your music. That way, you can add music from different locations to CherryMusic.

Replace “PATH_TO_MUSIC_COLLECTION” with the absolute path to your music collection and instead of “MUSIC_COLLECTION_1” choose a name for your music collection. Repeat the last command if you wish to add music from other locations.

CherryMusic uses a database to search and access files in your music collection. Before you can use CherryMusic, you need to do an initial file database update:

To reflect changes in your music collection, you need to repeat this step every time you make changes to your music collection. If you have a not that powerful server (like the Raspberry Pi, that I use) and a large music collection, it may be wise to do the initial database update on a more powerful machine. On a standard computer, even very large music collections should not take longer than a few minutes.

Finally, start CherryMusic in a GNU Screen session:

Press [CTRL] + [a] and then [d] to detach from the GNU Screen session. To switch back to your normal user, do:

Open a web browser on a computer connected to the same LAN the CherryMusic server is in and go to “IP:PORT”, where “IP” is the IP of the server and “PORT” the port specified in the CherryMusic configuration file (defaults to “8080”).


Create an admin user and the basic setup is done.


Scripts and autostart

For simpler handling of CherryMusic, I wrote the following two scripts, which automate the process of starting and updating CherryMusic after the above guide was followed.

Script to start CherryMusic at boot and any other time needed:

Script to update CherryMusic:

Copy and paste both scripts and name them “” and “” respectively.

Make them executable and change their owner to the user “cherrymusic”:

To have CherryMusic automatically started on system bootup (e. g. between reboots), add the following to “/etc/rc.local” (issue “$ nano /etc/rc.local”):

Make sure to add the above two lines before “exit 0” at the bottom of the file.

Be aware, that at the moment this is only a workaround, as I am too lazy to create a proper init.d script, which makes sure that the CherryMusic service is always up and running.

Anyway, now you can effortlessly update and start/restart CherryMusic within seconds with your normal user in Debian.

To get the latest CherryMusic version, do:

To start/restart CherryMusic, do:


If you have set up dynamic DNS and enabled port forwarding on your router at home, you should already be able to remotely stream music over the internet with your CherryMusic server. However, your login data and music stream is sent unencrypted. For more security, I highly recommend to set up secure connections with OpenSSL. The downside is, that every time you connect to your CherryMusic server, your browser will complain, that the connection is untrusted since our SSL certificate is self-signed and not by an authority (which would cost money).

For remotely accessing CherryMusic over the internet, you should forward the following ports on your router:

  • For CherryMusic, port 8080 (default) — to allow CherryMusic access over the internet.
  • For CherryMusic with SSL, port 8443 (default) — to allow CherryMusic SSL access over the internet.

Now install and configure OpenSSL and generate a self-signed certificate (to be able to use SSL encryption):

Install “ssl-cert” to have the SSL stuff set up correctly, especially the group “ssl-cert”:

Next, add the CherryMusic user to the group “ssl-cert”, to have permissions to read the later generated private key file:

Finally, we need to generate the private key and certificate files. This is quite a complex topic, so this guide will just walk you through the steps to get a working basic configuration — without giving much explanation. It is based on this article.

The following steps need to be done as root, so switch users:

Generate the files in a save place, e. g. the root home directory:

Create a safe directory to generate the keys and certificates and enter it:

Generate a private key:

Create a certificate signing request (CSR). it is important that “Common Name” is filled in with the fully qualified domain name of the server to be protected by SSL: The “Common Name” must be (or the IP address must resolve to) the server name your clients use to contact your host. If this does not match, every time your clients connect to the server they will get a message asking them if they really want to use this server. Since you probably do not have a static IP from your internet provider anyway, but use dynamic DNS and a self-signed SSL certificate instead, do not bother too much. With dynamic DNS and a self-signed SSL certificate, your IP will still change often and your browser will not recognize the certificate. So you will get this security warning in your browser anyway — no matter what you enter in the “Common Name” field.

Backup the original generated private key file:

Remove the pass phrase from the key file, so that Apache HTTP Server does not ask for the pass phrase every time it gets restarted (That way Apache starts with SSL after a reboot/crash, provided you use Apache):

Generate a self-signed certificate, valid for 10 years:

Make sure, the (unencrypted) private key file (“server.key”) and the rest is owned and only readable by the owner “root” and the group “ssl-cert”:

Copy the private key file and the signed certificate into place (“-a” to preserve the owner, group and permissions):

Log out from the root acount:

Done. Last, configure CherryMusic to use SSL. For that, edit CherryMusic’s configuration file again (e. g. using “nano”):

and change the following lines accordingly:

Now, when you connect to CherryMusic, you should automatically be redirected to the SSL port and therefore have a secure connection. Your browser will complain about the untrusted connection and you will have to temporarely add an exception everytime you connect to CherryMusic. That can be annoying, I know, but it is the safest way.


24 thoughts on “How to install and configure CherryMusic on a Debian Wheezy (headless) server

  1. Great writeup! It shows, however, what an advantage a cherrymusic Debian package would be, so fewer people would have to do the work. 🙂

    Have you considered splitting the post into several parts? Smaller chunks like “Basic”, “Scripts and automation” and “SSL” could make the content easier to navigate and link to.

    I’d also suggest hosting the scripts as Gists (e.g. or something alike, to make them more maintainable and available, and to have the option of only showing parts of the code. (Never used them that way, but Gists can also be embedded into HTML with a tag. You’d have any change you make reflected here automatically.)

    Anyway, thanks for taking the time to document this! 🙂

    • Hello til,

      thanks a lot for your comment and suggestions! Yes, I thought about splitting this post into several parts. However, I prefer to have this topic in one post. It is not that complex that it needs splitting. In my opinion it is clear enough to have a few headlines, although I see the problem with linking to specific parts of this guide.
      Hosting the scripts as Gists is a neat idea. I may do that at some point in the future.
      Many thanks for your input!

        • Hello Sam,

          no, I did not write an init.d script for Debian yet. But someone else did:
          Please have a look at the link I posted in my reply in the comments below.
          I hope that helps.

    • Hello Tim,

      you could try to remove (or rename, if you want to keep a backup) the user.db file, but that will delete all CherryMusic users (not only the admin user) and probably make all playlists created up to this point owned by nobody. To do this, type the following in your shell (as the user that runs CherryMusic):

      $ mv ~/.local/share/cherrymusic/db/user.db ~/.local/share/cherrymusic/db/user.db.old

      This is not exactly resetting the password of a user, but will let CherryMusic forget all about it’s users. On the next startup, CherryMusic will ask you to create a new admin account – just like it did during the inital startup.
      If this does not do the trick for you, please head over to the project’s page on GitHub and open an issue there.

  2. When i have ssl enabled for some reason it breaks cherrymusic for mobile. ive only tested it on ios with multiple browsers but when ssl is enabled it will log in but when i go to play a song the start/pause button flickers between start and pause and nothing happens. disabling ssl fixes the problem. how can i fix this and keep ssl?

  3. I ‘ve installed CM from this guide and it works nicely, thank you, my problem now is getting the Lord-simon script to work. It just stops while in Python and complains “Permission denied” when the script is run, I’m wondering if I have to change the permissions on the script from root user/group to cherrymusic user/group

  4. Ok, crisis over, I made a noob mistake and had a space in the dir= portion of the script. so I can report the Lord-Simon script works to make Cherrymusic a service

    • Hello George,

      sorry for the late reply. Great to hear that the init script works for you now. However, be very careful with permissions!

      It just stops while in Python and complains “Permission denied” when the script is run, I’m wondering if I have to change the permissions on the script from root user/group to cherrymusic user/group

      It is generally bad practice to run services as root user/group. Unless needed, services should be run with an unpriveleged user/group. This is also true for CherryMusic. For the sake of security, CherryMusic should never be run as root user/group. I strongly recommend to create a dedicated user to run CherryMusic, as described in this blog post. This user and it’s group should then also be entered in the init script.

      And just for the record:
      Switching users from root to another will never solve permission issues as no other user has more permissions than the root user.
      On the other hand, switching to the root user to solve permission issues can be dangerous and make the system insecure (e.g. for running CherryMusic: see first point of this comment). Ideally, the root user should only be used to accomplish administative tasks.
      Have fun.

  5. Great stuff. All works as advertised with small exception. When the website is loaded on iPad (both Chrome and Safari) it does not play music. I didn’t have time to check logs to see if it is something obvious but any suggestions would be much appreciated.

  6. So, it is necessary that you plan your shoe budget
    before buying one. Bourne’s President, Thomas Mc
    – Claskie, always uses his creative imagery to make trendy shoes for men. Moccasin UGG slippers are quite popular among the men.

Leave a Reply

Your email address will not be published. Required fields are marked *