Installation¶

Two possible ways to install the Avalon Music Server are described below. One is very simple and designed to get you up and running as quickly as possible. The other is more involved and designed to run the Avalon Music Server in a production environment.

All of these instructions are based on a machine running Debian Linux, but they should be applicable to any UNIX-like operating system (with a few modifications).

Quick Start Installation¶

This section will describe an extremely simple installation of the Avalon Music Server. If you just want to play around with the Avalon Music Server and don’t have plans to run it in production, this guide is for you.

First, we’ll install the virtualenv tool.

$ apt-get install python-virtualenv

Next, create a virtual environment that we’ll install the Avalon Music Server into.

$ virtualenv ~/avalon

“Activate” the virtual environment.

$ source ~/avalon/bin/activate

Install the Avalon Music Server and Gunicorn.

$ pip install avalonms gunicorn

Scan your music collection and build a database with the meta data from it.

$ avalon-scan ~/path/to/music

Start the server.

$ gunicorn --preload avalon.app.wsgi:application

Then, in a different terminal, test it out!

$ curl http://localhost:8000/avalon/heartbeat

You should see the result OKOKOK if the server started correctly. To stop the server, just hit CTRL-C in the terminal that it is running in.

Production Installation¶

This section will describe one potential way to install, configure, and run the Avalon Music Server in production.

This particular installation uses Gunicorn, Supervisord, and Nginx. We’ll set it up so that it can be deployed to using the included Fabric files in the future. We’ll also make use of the bundled Gunicorn and Supervisor configurations.

Installing Dependencies¶

First, we’ll install the virtualenv tool, Supervisor and Nginx using the package manager.

$ apt-get install python-virtualenv supervisor nginx

Setting Up The Environment¶

Next, we’ll set up the environment on our server:

Create the group that will own the deployed code.

$ sudo groupadd dev

Add our user to it so that we can perform deploys without using sudo.

$ sudo usermod -g dev `whoami`

Create the directories that the server will be deployed into.

$ sudo mkdir -p /var/www/avalon/releases

Set the ownership and permissions of the directories.

$ sudo chown -R root:dev /var/www/avalon
$ sudo chmod -R u+rw,g+rw,o+r /var/www/avalon
$ sudo chmod g+s /var/www/avalon /var/www/avalon/releases

Add a new unprivileged user that the Avalon Music Server will run as.

$ sudo useradd --shell /bin/false --home /var/www/avalon --user-group avalon

Create a virtual environment that we’ll install the Avalon Music Server into.

$ virtualenv /var/www/avalon/releases/20140717214022

Set the “current” symlink to the virtual environment we just created. This is the path that we’ll we pointing our Supervisor and Gunicorn configurations at.

$ ln -s /var/www/avalon/releases/20140717214022 /var/www/avalon/current

Installing from PyPI¶

Now, let’s install the Avalon Music Server, Gunicorn, and a Sentry client into the virtual environment we just created.

$ /var/www/avalon/current/bin/pip install avalonms gunicorn raven

The Avalon Music Server has an embedded default configuration file. In addition to that, we’ll create our own copy of that configuration that we can customize.

$ /var/www/avalon/current/bin/avalon-echo-config > /var/www/avalon/local-settings.py

Avalon WSGI Application¶

We won’t configure the Avalon WSGI application here, as part of installation. For more information about the available configuration settings for it, see the WSGI Application section.

Gunicorn¶

The installed Avalon Music Server comes with a simple Gunicorn configuration file that is available at /var/www/avalon/current/share/avalonms/avalon-gunicorn.py (or ext/avalon-gunicorn.py in the codebase). This file configures Gunicorn to:

Bind the server to only the local interface, port 8000.
Spawn three worker processes that will handle requests.
Use preload mode so that the workers will be able to take advantage of copy-on-write optimizations done by the operating system to save RAM.

Supervisor¶

The installed Avalon Music server also comes with a simple Supervisord configuration file. This file runs the Avalon Music Server as an unprivileged user, uses the Gunicorn HTTP WSGI server, restarts it if it crashes, and pipes all output to a log file. This is available at /var/www/avalon/current/share/avalonms/avalon-supervisor-gunicorn.conf (or ext/avalon-supervisor-gunicorn.conf in the codebase).

When you installed Supervisor earlier (if you’re on Debian) it created a directory that configurations can be placed into: /etc/supervisor/conf.d. Copy the bundled Supervisor configuration file into this directory and set the owner and permissions appropriately.

$ sudo cp /var/www/avalon/current/share/avalonms/avalon-supervisor-gunicorn.conf /etc/supervisor/conf.d/
$ sudo chown root:root /etc/supervisor/conf.d/avalon-supervisor-gunicorn.conf
$ sudo chmod 644 /etc/supervisor/conf.d/avalon-supervisor-gunicorn.conf

Nginx¶

Though Gunicorn can run as an HTTP server, you should use a dedicated web server in front of it as a reverse proxy if you plan on exposing it on the public Internet. If so, Nginx is a solid, lightweight, easy to configure choice. In the instructions below, replace api.example.com with the domain that you wish to run the Avalon Music Server at.

When you installed Nginx earlier it created a directory that server configurations can be placed into: /etc/nginx/sites-available/ (if you’re on Debian). If you’re not on Debian the directory may be in a different location such as /etc/nginx/conf.d or you may have a single configuration file: /etc/nginx/nginx.conf.

If you have a directory for configurations, create a new file named api_example_com.conf with the contents below. If you only have a single configuration file, add the contents below inside the http section.

upstream avalon {
         server localhost:8000;
}

server {
   listen 80;
   server_name api.example.com;

   location /avalon {
            proxy_pass http://avalon;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
   }
}

If you’re on Debian, enable the configuration like so.

$ sudo ln -s /etc/nginx/sites-available/api_example_com.conf /etc/nginx/sites-enabled/

Start the Server¶

Now that everything is configured, let’s try starting Nginx and Supervisor (which will, in turn, start the Avalon Music Server) and testing it out.

$ sudo service supervisor start
$ sudo service nginx start
$ curl http://api.example.com/avalon/heartbeat

If everything was installed correctly, the curl command should return the string OKOKOK.