install-docker-compose.md 7.98 KB
Newer Older
David Trattnig's avatar
David Trattnig committed
1
2
3
4
5

# Docker Compose Installation

## Requirements

6
7
8
9
- Docker Engine 20.10+ ([installation documentation](https://docs.docker.com/engine/install/))
- Docker Compose 2.2+ ([installation documentation](https://docs.docker.com/compose/install/))
- Git ([installation documentation](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git))

10

11

12
## Preparations
13
14

Clone the meta repository to the server(s) you want to deploy AURA Web and/or AURA Playout:
15

16
17
18
```
git clone https://gitlab.servus.at/aura/meta.git
```
19

20
and check out the latest release:
21

22
23
24
```
git checkout tags/<release-version>
```
25

26
27
If you want to deploy an older version, check out the corresponding release tag in the repository.

28
To see which releases are available you can check in the [Gitlab UI](https://gitlab.servus.at/aura/meta/-/releases)
David Trattnig's avatar
David Trattnig committed
29
Or you can check the tags in the repository you have just cloned:
30

31
32
33
```
git tag
```
34

35
will show you all tags which should correspond to the releases.
36
37
38
39

```{admonition} Unstable releases
:class: tip

David Trattnig's avatar
David Trattnig committed
40
As long as there is no release, just take the latest commit on the `main` branch, which is checked out by default
41
42
```

David Trattnig's avatar
David Trattnig committed
43
44
## Deploy AURA Web

45
- All required files can be found under `meta/docker-compose/aura-web`. For all described commands you should be in that directory.
46
- Copy the `sample.env` to `.env` and set all values as needed
EorlBruder's avatar
EorlBruder committed
47
- Initialize the steering-container:
48

EorlBruder's avatar
EorlBruder committed
49
50
51
```
docker-compose run --rm steering ./run.sh init-db
```
52

53
54
```{admonition} Defining the host for production setups
:class: tip
55
You can use a public domain name or any locally defined hostname. For example by configuring `aura.local` in `/etc/hosts`. Keep in mind to use a LAN IP though. Using `localhost` or `127.0.0.1` for the production setup is not supported. Here you'd need to make adjustments on your own or use the dev-setup.
56
57
58
59
```

```{admonition} Changing the host
:class: alert
60
Any update of `AURA_HOST` in your `.env` file is not reflected in the actual configuration. In such cases you either need to manually update the relevant OIDC client database tables, or you simple create new OIDC client IDs in the configuration. After that you can delete any old OIDC clients via the Steering admin interface `$AURA_HOST/steering/admin/oidc_provider/`.
61
62
```

63
- Start the services with docker-compose:
64

65
66
67
```bash
docker-compose up -d
```
David Trattnig's avatar
David Trattnig committed
68

69
70
In case you need/want to install the fixtures for initial programme data you need to *bash* into the already running container via

71
72
73
```bash
docker-compose exec steering bash
```
74

75
and then install the program fixtures by using the command
76

77
78
79
80
```bash
./manage.py loaddata fixtures/program/*.json
```

81
If you need to make changes to the `docker-compose.yml` you can create a `docker-compose.override.yml` and make the necessary adjustments in there. That way, your adjustments won't create conflicts.
82
83
84

We use named volumes for the data-volumes. That way all data will live in your docker-directory.

85
This deployment will make *aura-web* reachable in the following way:
86

87
88
89
90
91
92
- **Dashboard** is reachable directly under the domain given as `$AURA_HOST`
- **Steering** is reachable under `/steering`
- **Tank** is reachable under `/tank`
- **Track Service** endpoints of `engine-api` will be reachable under `/trackservice` (if `engine-api` is running)
- **Icecast**: If you enabled the optional Icecast server for the reverse proxy it will be reachable under `/icecast`. If you only enabled it, it will be reachable under port `8000` of the machine running *aura-web*.
- **Dashboard Clock** will be reachable from the configured network under the configured port. If you enabled it for the reverse-proxy, it will be reachable under `/clock`.
93

94
95
## Deploy AURA Playout

96
- All required files can be found under `meta/docker-compose/aura-playout`. For all described commands you need to change to this directory.
97
98
99
100
101
- Copy the `sample.env` to `.env` and set all values as needed
- In the folder `service-config/engine-core` copy the `sample.engine-core.ini`-file to a new `engine-core.ini` file and set values as needed
- Start the services with docker-compose:

```bash
102
docker-compose up -d
103
104
```

105
106
107
108
109
110
```{admonition} Latency issues with live analog audio
:class: tip

If you are facing latency issues with Engine Core while playing live from the analog audio source, we suggest you try to deploy Engine Core natively. To do so you'll need to comment out the COMPOSE_PROFILES variable in you `.env` file. Then, follow the documentation for a [bare-metal installation of Engine Core](https://gitlab.servus.at/aura/engine-core#prerequisites). We hope to solve the Docker latency issue in one of the coming releases.
```

111
## Update Containers
112

113
For updates of the components containers:
114

115
116
117
118
119
120
121
122
123
1. Pull the meta repository:
```bash
git pull
```
and check out the new release:
```bash
git checkout tags/<release-version>
```

124
125
126
1. Compare your `.env` file with the (now updated) `sample.env` and change your `.env` file accordingly. Take special note of new versions of the components. For `aura-playout`: If you use the docker container of `engine-core` you also want to compare the `sample.engine-core.ini` with your `engine-core.ini`

2. For the components having new versions: Check the release notes for changes you might need to take into account.
127

128
3. Pull the new images from Docker Hub:
129
130
131
132
133
134

```bash
docker-compose pull
```

5. Recreate the containers:
135

136
137
138
139
140
141
```bash
docker-compose up -d
```

## Update Databases

142
Manual steps for updating of the databases should only be necessary for `steering`. The other databases should be updated automatically by their services.
143

144
The Django migration scripts for `steering` are created during development and only need to be applied by the service to the database. This has to be done after updating the service.
145
146
147

To apply the migrations simply run:

148
```bash
149
150
docker-compose run --rm steering ./manage.py migrate
```
151

152
153
154
## Useful `docker` and `docker-compose` commands

Here you can find the [official documentation of docker-compose commands](https://docs.docker.com/compose/reference/).
155

156
157
158
Generally the commands are to be called from the folder in which the respective `docker-compose.yml` is in.

Below you find some useful examples.
159
160
161

### Show logs

162
163
To see the current logs of the containers running with `docker-compose`:

164
165
166
167
```bash
docker-compose logs -f --tail=100 <service-name>
```

168
169
In AURA Web the services are: steering, dashboard, dashboard-clock and tank (and icecast if you are using it).
In AURA Playout the services are: engine, engine-core and engine-api.
170
171
172
173
174
175

### (Re)Create and start the containers

```bash
docker-compose up -d
```
176
177

Starts all containers of services defined in the `docker-compose.yml` file of the folder the command is called from (and creates them if they didn't exist before).
178
If services, that are already running, were changed in any way docker-compose recreates them.
179
180

The parameter "`-d`" means it starts them as daemons in the background.
181

182
### Stop and remove services
183

184
185
If you wish to delete your deployment, all you need to do is destroying it with `docker-compose`:

186
187
188
189
```bash
docker-compose down
```

190
191
If you also wish to delete all data (in the Docker volumes), you can run the following command:

192
193
194
195
```bash
docker-compose down -v
```

196
197
198
### Pull images from Docker Hub

To pull the newest images from Docker Hub:
199

200
201
202
203
204
205
```bash
docker-compose pull
```

### Delete unused images

206
Since Docker does not automatically delete old images it can happen, that too much space is used by them on the server.
207
To delete images of containers not currently running, use:
208

209
210
211
212
```bash
docker system prune
```

213
This will <u>not</u> delete the Docker volumes (where the databases and therefore the persistent data lives).
214

215
216
217
218
219
220
221
222
223
224
225
226
227
228
### Log into a container

To *bash* into an already running container execute

```bash
docker-compose exec -it steering bash
```

To log into the database of a PostgreSQL container you can run

```bash
docker compose exec steering-postgres psql -U steering
```

David Trattnig's avatar
David Trattnig committed
229
230
## Deploy other Docker Images

231
If you prefer some individual deployment scenario, you can also [install single components using Docker only](install-docker.md). These Docker images are hosted on [https://hub.docker.com/u/autoradio](https://hub.docker.com/u/autoradio).