bare-metal-installation.md 5.45 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
11
12
13
14
15
16
17
18
19
20
21
22
    - [Configuration](#configuration)
    - [Running Engine](#running-engine)
    - [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
23
- [Python 3.8+](https://www.python.org/downloads/release/python-380/)
24
25
- [`pip`](https://pip.pypa.io/en/stable/)
- [`git`](https://git-scm.com/)
David Trattnig's avatar
David Trattnig committed
26
- [`virtualenv`](https://pypi.org/project/virtualenv/)
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

David Trattnig's avatar
David Trattnig committed
47
In case of an development environment, create a virtual environment for your Python dependencies:
48
49

```shell
David Trattnig's avatar
David Trattnig committed
50
python3.8 -m venv python
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
```

No worries, the resulting `python` directory is excluded from the git respostory.

To activate that environment, run

```shell
source python/bin/activate
```

Then, install the required dependencies

```shell
pip install -r requirements.txt
```

Create your base configuration from the sample configuration

```shell
# Development
cp config/sample.development.engine.ini config/engine.ini
# Production
cp config/sample.production.engine.ini config/engine.ini
```

David Trattnig's avatar
David Trattnig committed
76
77
### Setting up the database

David Trattnig's avatar
David Trattnig committed
78
Engine requires a PorstgreSQL database to cache any programme info locally:
David Trattnig's avatar
David Trattnig committed
79
80
81
82
83
84
85
86

```bash
# Additional Python packages for PostgreSQL
pip3 install -r contrib/postgresql-requirements.txt
# 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
87
> Important: You might want to change the password for the database user created by the relevant script.
David Trattnig's avatar
David Trattnig committed
88

89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
## Configuration

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

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

> Please note, if some configuration exists under `/etc/aura/engine.ini` the configuration by default is drawn from there.

While the configuration has plenty of configuration 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 the default settings too.

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

If you have defined a virtual env during the installation step you'll need to activate it first. You'll have to do so whenever you gonna start your development environment:

```shell
source python/bin/activate
```

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

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

Keep in mind you'll also need to start Engine Core separately

```shell
    engine-core$ ./run.sh
```

In order to have a full engine experience also the other AURA Components are required to be running. For convencience in starting the full environment checkout how to run Aura Web using Docker Compose within the [Meta Repository](https://gitlab.servus.at/aura/tank)

## 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

Now, given you are in the engine's home directory `/opt/aura/engine/`, simply type following to start the services:

```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)
- [Setting up the Audio Store [meta]](https://gitlab.servus.at/aura/meta/-/blob/master/docs/setup-audio-store.md)