bare-metal-installation.md 5.69 KB
Newer Older
1
2
3
4
5
6
7
# Install for Development

<!-- TOC -->

- [Install for Development](#install-for-development)
    - [Prerequisites](#prerequisites)
    - [Preparation](#preparation)
David Trattnig's avatar
David Trattnig committed
8
        - [Setting up the database](#setting-up-the-database)
9
10
    - [Configuration](#configuration)
    - [Running Engine](#running-engine)
David Trattnig's avatar
David Trattnig committed
11
        - [Starting dependencies](#starting-dependencies)
12
13
14
15
16
17
18
19
20
21
22
23
    - [Daemonized Engine](#daemonized-engine)
        - [Running with Systemd](#running-with-systemd)
        - [Running with Supervisor](#running-with-supervisor)
    - [Logging](#logging)
    - [Read more](#read-more)

<!-- /TOC -->

## Prerequisites

Aura Engine runs on any modern Debian-based OS. It requires at least

David Trattnig's avatar
David Trattnig committed
24
- [Python 3.8+](https://www.python.org/downloads/release/python-380/)
25
26
- [`pip`](https://pip.pypa.io/en/stable/)
- [`git`](https://git-scm.com/)
27
- [PostgreSQL 13+](https://www.postgresql.org/)
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


**Setting up the project structure**

Then clone all `engine` related projects to some development folder. In production we recommend `/opt/aura/` as the system base.

```bash
mkdir ~/code/aura
cd ~/code/aura
git clone https://gitlab.servus.at/autoradio/engine
git clone https://gitlab.servus.at/autoradio/engine-core
git clone https://gitlab.servus.at/autoradio/engine-api
     ...
```

If you are developing engine you also might want the projects `steering`, `dashboard` and `tank` in there, or you'll start them with Docker Compose (see [how to run Aura Web with Docker](https://gitlab.servus.at/autoradio/meta) in the [meta](https://gitlab.servus.at/autoradio/meta) repository)

## Preparation

47
Install dependencies:
48
```shell
49
50
51
52
53
54
55
56
apt install \
    python3-flask \
    python3-flask-sqlalchemy \
    python3-http-parser \
    python3-psycopg2 \
    python3-requests \
    python3-sqlalchemy \
    python3-validators
57
58
59
60
61
62
```

Create your base configuration from the sample configuration

```shell
# Development
David Trattnig's avatar
David Trattnig committed
63
cp config/sample-development.engine.ini config/engine.ini
64
# Production
David Trattnig's avatar
David Trattnig committed
65
cp config/sample-production.engine.ini config/engine.ini
66
67
```

David Trattnig's avatar
David Trattnig committed
68
69
### Setting up the database

David Trattnig's avatar
David Trattnig committed
70
Engine requires a PorstgreSQL database to cache any programme info locally:
David Trattnig's avatar
David Trattnig committed
71
72
73
74
75
76

```bash
# Create database and user (change password in script)
sudo -u postgres psql -f contrib/postgresql-create-database.sql
```

David Trattnig's avatar
David Trattnig committed
77
> Important: You might want to change the password for the database user created by the relevant script.
David Trattnig's avatar
David Trattnig committed
78

79
80
81
82
83
84
85
86
## Configuration

In your development environment edit following file to configure the engine:

```shell
./config/engine.ini
```

David Trattnig's avatar
David Trattnig committed
87
> Please note, if some configuration exists under `/etc/aura/engine.ini` the configuration by default is drawn from there. This overrides any configuration located in `./engine/config`.
88

David Trattnig's avatar
David Trattnig committed
89
While the configuration file has plenty of options, you only need to set a few mandatory ones, given you are running the other components (such as 'engine-core', "engine-api" etc.) at their default settings too.
90
91
92
93
94
95
96
97
98
99

Required modifications are:
    - The password `db_pass` for the local database holding scheduling information
    - The app secret `api_tank_secret` for connecting to [AURA Tank](https://gitlab.servus.at/aura/tank)

## Running Engine

There's a convencience script `run.sh` to get engine started

```shell
David Trattnig's avatar
David Trattnig committed
100
engine$ ./run.sh
101
102
```

David Trattnig's avatar
David Trattnig committed
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
The script executes the *default target*, which is usually `dev` for development environments.

You can call this target explicitely too:

```shell
engine$ ./run.sh dev
```

Or run Engine in production mode:

```shell
engine$ ./run.sh prod
```

For details on the run script, consult the [AURA CLI documentation](https://gitlab.servus.at/aura/meta/-/blob/master/docs/administration/cli.md).

### Starting dependencies

You'll also need to start Engine Core separately.
David Trattnig's avatar
David Trattnig committed
122
123

> Note it should not matter in which order you start Engine and Engine Core.
124
125

```shell
David Trattnig's avatar
David Trattnig committed
126
engine-core$ ./run.sh
127
128
```

David Trattnig's avatar
David Trattnig committed
129
130
131
Last but not least, Engine API is the target service to store playlogs, health information and details for the [Studio Clock](https://gitlab.servus.at/aura/dashboard-clock).

```shell
David Trattnig's avatar
David Trattnig committed
132
engine-api$ ./run.sh
David Trattnig's avatar
David Trattnig committed
133
134
135
```

In order to have the complete Engine experience, other AURA Components are required to be running too. Checkout the [Meta Repository](https://gitlab.servus.at/aura/meta) on how to run for example AURA Web using Docker Compose.
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

## Daemonized Engine

For this you can utilize either [Systemd](https://systemd.io/) or [Supervisor](http://supervisord.org/). Please check the their manuals on how to use these services.

The daemon configs are expecting you run engine under the user `engineuser` and being located under `/opt/aura/engine`, `/opt/aura/engine-api` and `/opt/aura/engine-core` respectively. Do prepare the project root and permissions you can use the script `scripts/initialize-systemd.sh`. To create the matching user and audio group membership run `scripts/create-engineuser.sh`.

### Running with Systemd

Copy the unit files in  `/opt/aura/engine/config/systemd/aura-engine.service` to your systemd unit directory, and reload the systemd daemon:

```shell
cp /opt/aura/engine/config/systemd/* /etc/systemd/system/
systemctl daemon-reload
```

### Running with Supervisor

David Trattnig's avatar
David Trattnig committed
154
Now, given you are in the engine's home directory like `/opt/aura/engine/`, simply type following to start the services:
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

```shell
supervisord
```

This picks up the supervisor configuration provided in the local `supervisord.conf` and the service configurations located in `config/supervisor/*.conf`.

Then you'll need to reload the supervisor configuration using `sudo`:

```shell
sudo supervisorctl reload
```

## Logging

All Engine logs can be found under `./logs`.

## Read more

- [Bare Metal Installation](docs/bare-metal-installation.md)
- [Developer Guide](docs/developer-guide.md)
David Trattnig's avatar
David Trattnig committed
176
- [Setting up the Audio Store [meta]](https://gitlab.servus.at/aura/meta/-/blob/master/docs/administration/setup-audio-store.md)