aircox/README.md

![](/logo.png)

A platform to manage radio schedules, website content, and more. It uses the power of great tools like Django or Liquidsoap.

This project is distributed under GPL version 3. More information in the LICENSE file, except for some files whose license is indicated inside source code.

## Features
* **streams**: multiple random music streams when no program is played. We also can specify a time range and frequency for each;
* **diffusions**: generate diffusions time slot for programs that have schedule informations. Check for conflicts and rerun.
* **liquidsoap**: create a configuration to use liquidsoap as a stream generator. Also provides interface and control to it;
* **sounds**: each programs have a folder for its podcast. Aircox detects updates, can run quality check, import related playlist (timestamped or position in track list). Sounds can be defined as excerpts or as archives.
* **log**: keep a trace of every played/loaded sounds on the stream generator.
* **admin**: admin user interface.
* **cms**: content management system.


## Architecture and concepts
Aircox is divided in two main modules:
* `aircox`: basics of Aircox (programs, diffusions, sounds, etc. management); interface for managing a website with Aircox elements (playlists, timetable, players on the website);
* `aircox_streamer`: interact with application to generate audio stream (LiquidSoap);

## Development setup
Start installing a virtual environment :

```
virtualenv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements_tests.txt
```

Then copy the default settings and initiate the database :

```
cp instance/settings/sample.py instance/settings/settings.py
python -c "from django.core.management.utils import get_random_secret_key; print('SECRET_KEY = \"%s\"' % get_random_secret_key())" >> instance/settings/settings.py
DJANGO_SETTINGS_MODULE=instance.settings.dev ./manage.py migrate
```

Finally test and run the instance using development settings, and point your browser to http://localhost:8000 :

```
DJANGO_SETTINGS_MODULE=instance.settings.dev pytest
DJANGO_SETTINGS_MODULE=instance.settings.dev ./manage.py runserver
```

Before requesting a merge, enable pre-commit :

```
pip install pre-commit
pre-commit install
```

## Installation
Running Aircox on production involves:
* Aircox modules and a running Django project;
* a supervisor for common tasks (sounds monitoring, stream control, etc.) -- `supervisord`;
* a wsgi and an HTTP server -- `gunicorn`, `nginx`;
* a database supported by Django (MySQL, SQLite, PostGresSQL);

### Scripts
Are included various configuration scripts that can be used to ease setup. They
assume that the project is present in `/srv/apps/aircox`:

* cron: daily cron configuration for the generation of the diffusions
* supervisorctl: audio stream generation, website, sounds monitoring
* nginx: sample config file (must be adapted)

The scripts are written with a combination of `cron`, `supervisord`, `nginx`
and `gunicorn` in mind.


### Dependencies
For python dependencies take a peek at the `requirements.txt` file, plus
dependencies specific to Django (e.g. for database: `mysqlclient` for MySql
database server).

External applications & modules:
* `liquidsoap`: `aircox` (generation of the audio streams)
* `sox`: `aircox` (check sounds quality and metadatas)
* `gunicorn`: WSGI server to be used in production (installed along as dependency)
* `supervisord`: supervisor
* note there might be external dependencies for python's Pillow too
* sqlite, mysql or any database library that you need to run a database, that is supported by Django (+ eventual python deps)
* gzip: archive logs

Development dependencies:
* `npm`, `webpack`: thoses are used for assets managements and development.

### Setup environment
All scripts and files assumes that:
- you have cloned aircox in `/srv/apps/` (such as `/srv/apps/aircox/README.md`)
- you have a supervisor running (we have scripts for `supervisord`)
- you use `gunicorn` as WSGI server (otherwise, you'll need to remove it from the requirement list)

This installation process uses a virtualenv, including all provided scripts.

```
# setup virtual env and activate
virtualenv venv
source venv/bin/activate
# install requirements
pip install -r requirements.txt
```

### Configuration
You must write a settings.py file in the `instance/settings` directory (you can just
copy and paste `instance/settings/sample.py`. There still is configuration
required in this file, check it in for more info.


### Installation and first run
Create the database if needed, and generate the tables:

```bash
# apply dependencies' migrations
./manage.py makemigrations
# create the database
./manage.py migrate --fake-initial
# create a super-user (needed in order to access the administration)
./manage.py createsuperuser
```

You must then configure the programs, schedules and audio streams. Start the
server from this directory:

```bash
./manage.py runserver
```

You can access to the django admin interface at `http://127.0.0.1:8000/admin`.

From the admin interface:
* create a Station
* create all the Programs and complete their Schedules
* defines Outputs for the streamer (look at Liquidsoap documentation for
  more information on how to configure it)

Once the configuration is okay, you must start the *controllers monitor*,
that creates configuration file for the audio streams using the new information
and that runs the appropriate application (note that you dont need to restart it
after adding a program that is based on schedules).

If you use supervisord and our script with it, you can use the services defined
in it instead of running commands manually.

## More informations
There are extra informations in `aircox/README.md` and `aircox_streamer/README.md`.