Commit 537840e7 authored by David Trattnig's avatar David Trattnig
Browse files

Docs: Remove content provided by Sphinx

parent 93ae6d70
<img src="../../assets/images/aura-logo.png" width="250" />
# AURA Command Line Interface (CLI)
There are two types of **Command Line Interfaces**:
......@@ -11,26 +9,6 @@ There are two types of **Command Line Interfaces**:
> Note: Not yet all projects have CLI support implemented consistently. See https://gitlab.servus.at/aura/meta/-/issues/57 for progress on consolidated functionality.
> TODO: In the future the `run.sh` scripts [should be replaced by a proper CLI Framework](https://gitlab.servus.at/aura/meta/-/issues/45).
1. [AURA Command Line Interface (CLI)](#aura-command-line-interface-cli)
1. [META CLI](#meta-cli)
1. [META CLI for SysOps](#meta-cli-for-sysops)
2. [META CLI for Release Management](#meta-cli-for-release-management)
2. [Project CLI for Development and isolated actions](#project-cli-for-development-and-isolated-actions)
1. [Default action](#default-action)
2. [Local Commands](#local-commands)
1. [Start Development Server](#start-development-server)
2. [Start Production Server](#start-production-server)
3. [Run the test-suite](#run-the-test-suite)
3. [Docker Commands](#docker-commands)
1. [Docker Build](#docker-build)
2. [Docker Push](#docker-push)
3. [Docker Run](#docker-run)
1. [Development](#development)
2. [Debugging](#debugging)
3. [Production](#production)
4. [Docker Test](#docker-test)
## META CLI
### META CLI for SysOps
......@@ -94,7 +72,7 @@ Pushes the build image to https://hub.docker.com/u/autoradio.
./run.sh docker:push
```
#### Docker Run
#### Docker Run
##### Development
......@@ -113,7 +91,7 @@ Also note:
Some projects like [Engine Core](https://gitlab.servus.at/aura/engine-core) provide a `debug` target to debug container development.
In contrast to the development mode, only the log file is `tail`ed, after starting the container.
In contrast to the development mode, only the log file is `tail`ed, after starting the container.
```bash
./run.sh docker:debug
......
# Administration Guide
Here you shall find everything required to make and keep AURA up- and running.
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Docker Compose Installation
1. [Docker Compose Installation](#docker-compose-installation)
1. [Requirements](#requirements)
2. [Preparations](#preparations)
3. [Deploy AURA Web](#deploy-aura-web)
4. [Deploy AURA Playout](#deploy-aura-playout)
5. [Update Containers](#update-containers)
6. [Update Databases](#update-databases)
7. [Useful `docker` and `docker-compose` commands](#useful-docker-and-docker-compose-commands)
1. [Show logs](#show-logs)
2. [(Re)Create and start the containers](#recreate-and-start-the-containers)
3. [Stop and remove services](#stop-and-remove-services)
4. [Pull images from Docker Hub](#pull-images-from-docker-hub)
5. [Delete unused images](#delete-unused-images)
8. [Deploy other Docker Images](#deploy-other-docker-images)
## Requirements
- Docker Engine 20.10+ ([installation documentation](https://docs.docker.com/engine/install/))
......@@ -49,14 +32,12 @@ git tag
will show you all tags which should correspond to the releases.
```{admonition} Unstable releases
:class: tip
As long as there is no release, just take the latest commit on the `main` branch, which is checked out by default)
```
## Deploy AURA Web
- All required files can be found under `meta/docker-compose/aura-web`. For all described commands you should be in that directory.
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Docker Installation
Docker images are hosted on [hub.docker.com/u/autoradio](https://hub.docker.com/u/autoradio).
1. [Docker Installation](#docker-installation)
1. [Deploy AURA Web](#deploy-aura-web)
1. [Steering](#steering)
2. [Tank](#tank)
3. [Dashboard](#dashboard)
4. [Dashboard Clock](#dashboard-clock)
2. [Deploy AURA Playout](#deploy-aura-playout)
1. [Engine Core](#engine-core)
2. [Engine API](#engine-api)
3. [Engine Control](#engine-control)
## Deploy AURA Web
*to be defined*
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Maintenance
*to be defined*
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Deployment Scenarios
The following network diagrams outline ideas on deployment scenarios.
1. [Deployment Scenarios](#deployment-scenarios)
1. [Single Instance](#single-instance)
2. [Advanced](#advanced)
3. [High Availability](#high-availability)
## Single Instance
This is the most simple scenario for setting things up, as all services reside on the same machine. The downsite is, that any hardware issues or the need for restarting the server has an immediate effect on the full array of services.
> Note, `engine-core` is currently supported with native deployment only
[<img src="https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-network--single.png" />](https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-network--single.png)
[<img src="https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/aura-network--single.png" />](https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/aura-network--single.png)
## Advanced
......@@ -24,7 +17,7 @@ Here we utilize at least two machines for services: One for all web-facing appli
> Note, `engine-core` is currently supported with native deployment only
[<img src="https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-network--advanced.png" />](https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-network--advanced.png)
[<img src="https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/aura-network--advanced.png" />](https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/aura-network--advanced.png)
## High Availability
......@@ -32,5 +25,5 @@ That's the most sophisticated approach where your radio should never ever go dow
> Note, this is a future scenario. Not all required service are available yet.
[<img src="https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-network--ha.png" />](https://gitlab.servus.at/aura/meta/-/raw/master/assets/images/aura-network--ha.png)
[<img src="https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/aura-network--ha.png" />](https://gitlab.servus.at/aura/meta/-/raw/main/assets/images/aura-network--ha.png)
<img src="../../assets/images/aura-logo.png" width="250" />
# OpenID Client Configuration
1. [OpenID Client Configuration](#openid-client-configuration)
1. [Required OIDC Clients](#required-oidc-clients)
2. [Registering clients at Steering](#registering-clients-at-steering)
1. [Registering OIDC clients on the command-line](#registering-oidc-clients-on-the-command-line)
2. [Registering OIDC clients via the admin interface](#registering-oidc-clients-via-the-admin-interface)
1. [Create an RSA Key](#create-an-rsa-key)
2. [Create OIDC client for Dashboard](#create-oidc-client-for-dashboard)
3. [Create OIDC client for Tank](#create-oidc-client-for-tank)
3. [Setting the client configuration](#setting-the-client-configuration)
1. [Configuring Dashboard](#configuring-dashboard)
2. [Configuring Tank](#configuring-tank)
AURA is using [OpenID](https://en.wikipedia.org/wiki/OpenID) for authentication and authorizing
AURA is using [OpenID](https://en.wikipedia.org/wiki/OpenID) for authentication and authorizing
access to restricted API endpoints.
More specifically we are using [OpenID Connect (OIDC)](https://openid.net/connect/) for the OpenID handshakes.
[Steering](https://gitlab.servus.at/aura/steering) is the central OpenID provider. All applications requesting access,
need to get an authorization from Steering.
need to get an authorization from Steering.
Those applications are called *OIDC clients*.
......@@ -58,7 +43,7 @@ steering$ python manage.py create_oidc_client dashboard public -r "id_token toke
**Important:** Remember to note the client id and secret for the configuration section below.
1. Create OIDC client for Tank
```bash
steering$ python manage.py create_oidc_client tank confidential -r "code" -u https://localhost:8040/auth/oidc/callback
```
......@@ -146,7 +131,7 @@ VUE_APP_API_STEERING_OIDC_REDIRECT_URI_SILENT = http://localhost:8080/oidc_callb
Then set the client id and secret, which you noted from the previous step:
```ini
VUE_APP_OIDC_CLIENT_ID = %YOUR_ID%
VUE_APP_OIDC_CLIENT_ID = %YOUR_ID%
```
Additionally, confirm that your configured Steering URL and port is also matching the instance Steering is running at:
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Setting up the Audio Store
The *Audio Store* is a folder which is utilized by AURA Tank and Engine to exchange audio files.
......@@ -12,18 +9,6 @@ In case you are hosting Engine and Tank on the same machine (e.g. in development
this documentation. Just think about pointing Tank's audio directory to `engine-core/audio/source`
or create a symlink to do so behind the curtains.
<!-- TOC -->
1. [Setting up the Audio Store](#setting-up-the-audio-store)
1. [Share Location](#share-location)
2. [Share Type](#share-type)
3. [Setting up SSHFS](#setting-up-sshfs)
1. [Configuring Engine](#configuring-engine)
2. [Configuring Tank](#configuring-tank)
4. [Read more](#read-more)
<!-- /TOC -->
By default [Engine Core](https://gitlab.servus.at/aura/engine-core) expects audio files shared by Tank in `engine-core/audio/source`.
Now, this folder must be somehow writable by Tank.
......@@ -41,7 +26,7 @@ You have following options where your share can be located:
2. **Physical directory where the Engine lives, mounted to Tank**. This may cause an issue with the mount, when no network connection to Engine
is unavailable or the instance is rebooting.
3. **Physical directory where the Tank lives, mounted to Engine.** This may cause an issue with the mount, when no network connection to Tank
3. **Physical directory where the Tank lives, mounted to Engine.** This may cause an issue with the mount, when no network connection to Tank
is unavailable or the instance is rebooting.
4. **Central Data Store or *Storage Box*** which is mountet to Engine and Tank. In this case a downtime of the store make both, Engine and Tank
......
<img src="../assets/images/aura-logo.png" width="250" />
# API Specification
[← Developer Guide | Overview](index.md)
This page gives an overview of the Aura API Endpoints.
<!-- TOC -->
1. [API Specification](#api-specification)
1. [Steering API](#steering-api)
2. [Engine API](#engine-api)
3. [Tank API](#tank-api)
4. [CBA (Cultural Broadcasting Archive)](#cba-cultural-broadcasting-archive)
5. [Read more](#read-more)
<!-- /TOC -->
## Steering API
[Steering](https://gitlab.servus.at/aura/steering) is the source of the program/schedule for AURA.
......
# Bug Reports
[← Developer Guide | Overview](index.md)
Tell us your problems!
Tell us about your problems!
But please use the bug report template below.
1. [Bug Reports](#bug-reports)
1. [Contact us via Matrix](#contact-us-via-matrix)
2. [Create a ticket on GitLab](#create-a-ticket-on-gitlab)
3. [Bug Reporting Template](#bug-reporting-template)
## Contact us via Matrix
You can find as on [Matrix](https://matrix.to/#/#aura:freie-radios.de) which is also our primary channel for communication.
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Coding Conventions
[← Developer Guide | Overview](index.md)
Here you find an overview of our conventions on coding and version control.
## git
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Schedules and conflict resolution
[← Developer Guide | Overview](index.md)
1. [Schedules and conflict resolution](#schedules-and-conflict-resolution)
1. [Overview](#overview)
2. [Create/update schedule](#createupdate-schedule)
3. [Return](#return)
4. [Solutions](#solutions)
1. [theirs (always possible)](#theirs-always-possible)
2. [ours (always possible)](#ours-always-possible)
3. [theirs-start](#theirs-start)
4. [ours-start](#ours-start)
5. [theirs-end](#theirs-end)
6. [ours-end](#ours-end)
7. [theirs-both](#theirs-both)
8. [ours-both](#ours-both)
1. [Multiple collisions](#multiple-collisions)
5. [Errors](#errors)
1. [Fatal errors that require the schedule's data to be corrected and the resolution to restart](#fatal-errors-that-require-the-schedules-data-to-be-corrected-and-the-resolution-to-restart)
2. [Conflict-related errors which can be resolved for each conflict:](#conflict-related-errors-which-can-be-resolved-for-each-conflict)
6. [Read more](#read-more)
## Overview
Creating timeslots is only possible by creating/updating a schedule.
When creating/updating a schedule by giving the schedule data:
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Contributing to AURA
[← Developer Guide | Overview](index.md)
1. [Contributing to AURA](#contributing-to-aura)
1. [Code of Conduct](#code-of-conduct)
2. [How can I contribute?](#how-can-i-contribute)
3. [Contribution Guidelines](#contribution-guidelines)
4. [Contributors](#contributors)
5. [Sponsorship](#sponsorship)
6. [Licensing](#licensing)
7. [License](#license)
## Code of Conduct
We inherit the [Contributor Covenant](code_of_conduct.md).
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Default hosts and ports
[← Developer Guide | Overview](index.md)
Here you find the default hosts and ports for all AURA applications.
1. [Default hosts and ports](#default-hosts-and-ports)
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Developer Guide | Architecture
[← Developer Guide | Overview](index.md)
This section holds details on the AURA Architecture.
For more specific documentation please consult the individual `README.md` files [in the relevant projects](https://gitlab.servus.at/aura).
1. [Developer Guide | Architecture](#developer-guide--architecture)
1. [Architecural overview](#architecural-overview)
2. [Component spaces, components and dependencies](#component-spaces-components-and-dependencies)
3. [Diagrams](#diagrams)
1. [Network Diagramm](#network-diagramm)
2. [Data Model](#data-model)
1. [Simplified Data Model](#simplified-data-model)
2. [Full Data Model](#full-data-model)
4. [AURA API](#aura-api)
5. [Conflict Resolution for the scheduling timetable](#conflict-resolution-for-the-scheduling-timetable)
## Architecural overview
Some of our core organisational and architectural requirements for AURA are:
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Developer Guide | Development
[← Developer Guide | Overview](index.md)
Learn how to get started on AURA development.
For more specific documentation please consult the individual `README.md` files [in the relevant projects](https://gitlab.servus.at/aura).
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Developer Guide | Installation
[← Developer Guide | Overview](index.md)
For Development the native installation as outlined in the `README.md` of each project is 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.
......@@ -13,11 +9,6 @@ In case you are not developing on some certain project, but need it as a depende
> Note: For production we highly recommend to run AURA using Docker and Docker Compose as outlined in the [Administration Guide](../administration/index.md)
1. [Developer Guide | Installation](#developer-guide--installation)
1. [Prepare your Development Environment](#prepare-your-development-environment)
2. [Order of configuration](#order-of-configuration)
3. [Configuring the OpenID Clients](#configuring-the-openid-clients)
## Prepare your Development Environment
It is recommended to clone all projects for example in such folder structure:
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Developer Guide | Planning
[← Developer Guide | Overview](index.md)
This is the place to get started with AURA project planning and related workflows.
1. [Developer Guide | Planning](#developer-guide--planning)
1. [Sprint Planning](#sprint-planning)
2. [Planned Versions and Release Criteria](#planned-versions-and-release-criteria)
3. [Release Managment](#release-managment)
This is the place to get started with AURA project planning and related workflows.
## Sprint Planning
......
<img src="../../assets/images/aura-logo.png" width="250" />
# Developer Guide | Release Management
[← Developer Guide | Overview](index.md)
This section holds details on AURA release management.
1. [Developer Guide | Release Management](#developer-guide--release-management)
1. [SemVer Versioning Scheme](#semver-versioning-scheme)
2. [Current Release](#current-release)
3. [General Release Workflow](#general-release-workflow)
1. [Releasing a single component](#releasing-a-single-component)
2. [Releasing a software bundle](#releasing-a-software-bundle)
4. [When is the CICD Release Pipeline triggered and what does it do?](#when-is-the-cicd-release-pipeline-triggered-and-what-does-it-do)
## SemVer Versioning Scheme
Release names are defined according to the [Semantic Versioning 2.0.0](https://semver.org/) versioning scheme.
......
# User Guide
This guide helps in using the User Interface for radio hosts and programme coordinators.
......
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