Commit 3433c9cf authored by David Trattnig's avatar David Trattnig
Browse files

Docs: Combined improvements

parent 10f27c32
......@@ -3,7 +3,7 @@
## The naming scheme
Automated Radio, AutoRadio or AuRa, follows an "*Automobile-naming-scheme". All the components are named after some crucial parts of a car:
Automated Radio, AutoRadio, AuRa or AURA, follows an "*Automobile-naming-scheme*". All the components are named after some crucial parts of a car:
- **Steering**: This is the single source of thruth, holding all the data and steering some radios broadcast.
- **Tank**: That's where your shows, tunes and recordings are mangaged. Fuelling your broadcast with materials.
......@@ -25,11 +25,11 @@ The aforementioned naming scheme, is used as a basis for name-spacing services:
| Service | Required | Description |
|--- |--- |--- |
| steering | [x] | Single-source of truth, holding all radio, show, host<br/>and scheduling data |
| tank | [x] | Upload, download and media-managent |
| dashboard | [x] | Backend User Interface |
| dashboard-clock | [ ] | Studio Clock |
| engine | [x] | Control and scheduling for the play-out |
| engine-core | [x] | Play-out Engine |
| engine-api | [ ] | API for playlogs and track service |
| player | [ ] | Library for building frontend based on web components |
\ No newline at end of file
| steering | `x` | Single-source of truth, holding all radio, show, host<br/>and scheduling data |
| tank | `x` | Upload, download and media-managent |
| dashboard | `x` | Backend User Interface |
| dashboard-clock | | Studio Clock |
| engine | `x` | Control and scheduling for the play-out |
| engine-core | `x` | Play-out Engine |
| engine-api | | API for playlogs and track service |
| player | | Library for building frontend based on web components |
\ No newline at end of file
......@@ -12,7 +12,6 @@ Some of our core organisational and architectural requirements for AURA are:
* **reuse of existing components**: we do not want to reinvent the wheel. Several stations already developed single components as free software and we can adapt and build on those
* **modern frameworks**: we do not code from scratch but use modern application development frameworks which provide maintainability as well as security
> Note:
```{admonition} Outdated diagram
:class: tip
......@@ -41,10 +40,6 @@ This is almost the complete picture of the Steering data model.
<a href="https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/steering_data_model.png"><img src="https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/steering_data_model.png" width="800" /></a>
## AURA API
Find the API specification at [api.aura.radio](https://api.aura.radio).
## Conflict Resolution for the scheduling timetable
Check out the [Conflict Resolution Documentation](misc/conflict-resolution.md) page.
......@@ -31,11 +31,13 @@ We utilize an *API-first* approach. APIs are specified using OpenAPI 3. Find the
## Developer Installation
For Development the native installation as outlined in the `README.md` of each project is recommended.
For Development the native installation as outlined in the `README` of individual [repositories](https://code.aura.radio) recommended.
In case you are not developing on some certain project, but need it as a dependency only, you can install it using the Docker Image deployment variant.
```{admonition} Docker Compose Deployments
:class: tip
> Note: For production we highly recommend to run AURA using Docker and Docker Compose as outlined in the [Administration Guide](../administration/index.md)
For production we highly recommend to run AURA using Docker and Docker Compose as outlined in the [Administration Guide](../administration/index.md). But also as a developer you can benefit from the ease of an Docker Compose installation. For example when developing some Engine feature, you may want to run AURA Web with Docker Compose while testing.
```
### Prepare your Development Environment
......@@ -77,6 +79,6 @@ Dashboard and Tank authenticate against Steering using OpenID. We use [OpenID Co
## Component Documentation
For more specific documentation please consult the individual `README` files in the relevant repositories.
For more detailed documentation read the `README` files in the individual repositories.
You get an overview of all repositories at [code.aura.radio](https://code.aura.radio).
\ No newline at end of file
......@@ -190,11 +190,3 @@ Possible error messages are:
The 'solutions'-value was empty or does not exist. Provide a value of 'solution_choices'
* 'Given solution is not accepted for this conflict.':
The solution has a value which is not part of 'solution_choices'. Provide a value of 'solution_choices' (at least 'ours' or 'theirs')
## Read more
* [User Guide](docs/user/index.md)
* [Installation Guide](docs/administration/installation-guide.md)
* [Maintenance Guide](docs/administration/maintenance-guide.md)
* [API Specification](docs/development/api-definition.md)
* [Conflict Resolution](docs/development/conflict_resolution.pdf)
......@@ -85,7 +85,7 @@ use exactly the same string (and vice versa).
Note the *Client ID* to use in your Dashboard config file.
<a href="../../../assets/images/steering-openid-dashboard.png"><img src="../../../assets/images/steering-openid-dashboard.png" width="500" /></a>
<a href="https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/steering-openid-dashboard.png"><img src="https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/steering-openid-dashboard.png" width="800" /></a>
```{admonition} TODO
:class: alert
......@@ -113,7 +113,7 @@ http://localhost:8040/auth/oidc/callback
Note the *Client ID* and secret to use in your Tank config file.
<a href="../../../assets/images/steering-openid-tank.png"><img src="../../../assets/images/steering-openid-tank.png" width="500" /></a>
<a href="https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/steering-openid-tank.png"><img src="https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/steering-openid-tank.png" width="800" /></a>
```{admonition} TODO
:class: alert
......
# Release Management
## SemVer Versioning Scheme
## Semantic Versioning
Release names are defined according to the [Semantic Versioning 2.0.0](https://semver.org/) versioning scheme.
Release names are defined according to the [SemVer 2.0.0](https://semver.org/) versioning scheme.
The gitlab CI/CD pipeline for releases is configured to only accept tags that conform to this versioning scheme.
## Current Release
You can see the [project status & any available releases](https://pm.aura.radio) in our Wiki.
You can check [pm.aura.radio](https://pm.aura.radio) to learn about the project status & any available releases in our Wiki.
You can find releases of the components (engine, tank, steering, etc) on the respective gitlab repository site under "*Deployments -> Releases*". For releases of the pre-configured deployments (Docker Compose) you can look at the [releases in the meta repository](https://gitlab.servus.at/aura/meta/-/releases).
Find releases of the components (Engine, Tank, Steering, etc) on the respective Gitlab repository page under "*Deployments -> Releases*". For releases of the pre-configured deployments (Docker Compose) you can look at the [releases in the meta repository](https://gitlab.servus.at/aura/meta/-/releases).
## General Release Workflow
......@@ -33,7 +33,7 @@ The release of a complete software bundle is triggered from within the `meta` re
For the meta repository there is the speciality, that you should copy the release notes from the upgraded component releases since the last meta release into the meta release notes.
To document compatible versions of single components, use the "\<compoment\>_VERSION" variables found in the `sample.env` settings of the docker-compose setups of [aura-playout](../../docker-compose/aura-playout/sample.env) and [aura-web](../../docker-compose/aura-web/sample.env).
To document compatible versions of single components, use the `\<component\>_VERSION` variables found in the `sample.env` settings of the docker-compose setups of [aura-playout](../../docker-compose/aura-playout/sample.env) and [aura-web](../../docker-compose/aura-web/sample.env).
## When is the CI/CD Release Pipeline triggered and what does it do?
......@@ -44,13 +44,13 @@ The pipeline has two jobs:
The first job is triggered when a commit is made to the `main` branch or when a tag is pushed to the Gitlab repository of the component.
When there is a commit on the `main` branch, the built Docker image will be tagged "`unstable`". Unstable versions can be used in development/testing environments but should not be used in production environments.
When there is a commit on the `main` branch, the built Docker image will be tagged `unstable`. Unstable versions can be used in development/testing environments but should not be used in production environments.
When a tag is pushed (technically on any branch, but it should probably be done only on commits on the `main` branch), the Docker image built will be tagged both "latest" and "\<release version\>".
When a tag is pushed, and the build/push job is successful, it will then trigger the release job.
```{admonition} Alpha Status
```{admonition} Semantic versioning of releases
:class: tip
The chosen git tag will be the release name and the version of the Docker image. Therefore the pipeline script will enforce it to conform to [Semantic Versioning 2.0.0](https://semver.org/).
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment