bare-metal-installation.md 5.64 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
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
76
77
78
79
80
81
82
83
84
85
86
87
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
169
170
171
172
173
174
175
176
# Install for Development

<!-- TOC -->

- [Install for Development](#install-for-development)
    - [Prerequisites](#prerequisites)
- [Setting up the database](#setting-up-the-database)
    - [Preparation](#preparation)
    - [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

- [`Python 3.8+`](https://www.python.org/downloads/release/python-380/)
- [`pip`](https://pip.pypa.io/en/stable/)
- [`git`](https://git-scm.com/)
- ['virtualenv'](https://pypi.org/project/virtualenv/) (development only)
- DBMS server/client libraries for MariaDB or PostgreSQL (see below)

# Setting up the database

Depending on the DBMS you are planning to use you'll need to have the relevant server/client libaries to be present.

**MariaDB**

```shell
sudo apt install \
    python3.8-dev \
    default-libmysqlclient-dev \
    mariadb-server \
    libmariadbclient-dev
```

The following installation script sets up the initial databases and users.

```bash
  bash scripts/setup-db.sh
```

As soon as this is completed, carefully check if any error occured. In case your database has been setup automatically, note the relevant credentials for later use in your `engine.ini` configuration.

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

In case of an development environment, create a virtual env for your Python dependencies:

```shell
virtualenv -p python3.8 python
```

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

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