diff --git a/README.md b/README.md index 06f9998b1db5697c18458c25954e66a812cce27c..a3076c089688b1f84fbebb9dd9e1035656cf0a13 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,14 @@ specifically build for the requirements of community radios. - [Architecture](#architecture) - [Requirements](#requirements) - [Installation](#installation) - - [Start the Engine](#start-the-engine) + - [Install System Libraries](#install-system-libraries) + - [Install Engine](#install-engine) + - [Setup Database](#setup-database) + - [Configuration](#configuration) + - [Running Engine](#running-engine) + - [Development](#development) + - [Production](#production) + - [API Server](#api-server) - [Logging](#logging) - [About](#about) - [Resources](#resources) @@ -61,14 +68,15 @@ It is tested and coded on Debian Stretch and Ubuntu 18.0 with Python 3.6+. git clone https://gitlab.servus.at/autoradio/engine ``` -**Install System Libraries:** +### Install System Libraries Aura Engine requires at least Node 13 and Python 3.7. ```bash sudo apt install \ git \ - nodejs\ + supervisor \ + nodejs \ python3.7 python3.7-pip python3.7-dev \ redis-server \ libsndfile1 ffmpeg \ @@ -79,13 +87,21 @@ sudo apt install \ liquidsoap-plugin-all ``` -**Install Engine Packages:** +### Install Engine + +Development Environment: ```bash sudo ./install.sh ``` -**Setup Database:** +Production Environment: + +```bash +sudo ./install.sh prod +``` + +### Setup Database ```bash mysql -u root -p @@ -95,7 +111,7 @@ CREATE USER 'aura'@'localhost' IDENTIFIED BY 'secure-password'; GRANT ALL PRIVILEGES ON aura_engine.* TO 'aura'@'localhost'; ``` -**Configuration:** +### Configuration Run @@ -111,10 +127,12 @@ your time to carefully review those settings! Read more about detailed settings in the [Configuration Guide](docs/configuration-guide.md). -## Start the Engine +## Running Engine + +### Development -**Development:** While developing there is a simple convencience script `run.sh` +While developing there is a simple convencience script `run.sh` to get you started. Call the engine's components in following order: ```shell @@ -123,14 +141,19 @@ to get you started. Call the engine's components in following order: ./run.sh api # Starts the engine-api component ``` -**Production:** In production the process is slightly different to ensure the +In development mode Engine uses the [Flask](https://palletsprojects.com/p/flask/) development server. +This server should not be used in your production environment. + + +### Production + +In production the process is slightly different to ensure the engine's components are always running i.e. restart themselves after some system restart or crash. Therefore they are executed using a system service: ```bash systemctl start aura-engine systemctl start aura-lqs - systemctl start aura-api ``` and on system boot run following: @@ -140,9 +163,33 @@ and on system boot run following: systemctl enable aura-lqs ``` +#### API Server + +For production Engine API uses the WSGI HTTP Server [`Gunicorn`](https://gunicorn.org/). + +[`Supervisor`](http://supervisord.org/) is a preferable solution to run the gunicorn server +in the background and also start it automatically on reboot. + +**Start the API service with Supervisor** + +```shell + sudo supervisorctl reread + sudo supervisorctl update + sudo supervisorctl avail + sudo supervisorctl restart engine-api +``` + +In case you want to reload whole supervisor service + +```shell + sudo service supervisor restart +``` ## Logging +All Engine logs for production can be found in `/var/log/aura/engine` + + You can access the service logs using one of: ``` @@ -161,9 +208,12 @@ Aura Engine is the play-out engine of the Aura Radio Software Suite. Aura stands | [Steering](https://gitlab.servus.at/autoradio/pv) | [Dashboard](https://gitlab.servus.at/autoradio/dashboard) | [Tank](https://gitlab.servus.at/autoradio/tank) | [Engine](https://gitlab.servus.at/autoradio/engine) | -## Resources ## +## Resources * **Python**: https://docs.python.org/ * **Redis**: https://redis.io/ * **Liquidsoap**: https://www.liquidsoap.info/doc-1.4.0/ * **Jack Audio**: https://jackaudio.org/ +* **Flask**: https://palletsprojects.com/p/flask/ +* **Supervisor**: http://supervisord.org/ +* **Gunicorn**: https://gunicorn.org/ \ No newline at end of file