chore: release 3.0.0-alpha.13

This commit is contained in:
jo 2022-07-15 12:24:53 +02:00 committed by Jonas L
parent de7703ffa0
commit 28cec5100a
121 changed files with 1426 additions and 634 deletions

View file

@ -0,0 +1,2 @@
label: Setup
position: 00

View file

@ -0,0 +1,174 @@
---
title: Configuration
sidebar_position: 20
---
To configure LibreTime, you need to edit the `/etc/libretime/config.yml` file. This page describe the available options to configure your installation.
## General
The `general` section configure anything related to the legacy and API services.
```yml
general:
# The public url, this field is REQUIRED
public_url: https://example.com
# The internal API authentication key, this field is REQUIRED
api_key: some_random_generated_secret!
# List of origins allowed to access resources on the server, default is []
# The public url origin is automatically included
allowed_cors_origins: []
# How many hours ahead Playout should cache scheduled media files, default is 1
cache_ahead_hours: 1
# Authentication adaptor to use for the legacy service, default is local
# Specify a class like LibreTime_Auth_Adaptor_FreeIpa to replace the built-in adaptor
auth: local
```
In order to apply the changes made in this section, please restart the following services:
```
libretime-api
libretime-analyzer
libretime-celery
libretime-playout
```
## Database
The `database` section configure the PostgreSQL connection.
:::caution
Before editing this section be sure to update the PostgreSQL server with the desired values.
#### Changing a PostgreSQL user password
You can change the `libretime` PostgreSQL user password using:
```bash
sudo -u postgres psql -c "ALTER USER libretime PASSWORD 'new-password';"
```
:::
```yml
database:
# The hostname of the PostgreSQL server, default is localhost
host: localhost
# The port of the PostgreSQL server, default is 5432
port: 5432
# The name of the PostgreSQL database, default is libretime
name: libretime
# The username of the PostgreSQL user, default is libretime
user: libretime
# The password of the PostgreSQL user, default is libretime
password: some_random_generated_secret!
```
In order to apply the changes made in this section, please restart the following services:
```
libretime-api
```
## RabbitMQ
The `rabbitmq` section configure the RabbitMQ connection.
:::caution
Before editing this section be sure to update the RabbitMQ server with the desired values.
#### Changing a RabbitMq user password
You can change the `libretime` RabbitMQ user password using:
```bash
sudo rabbitmqctl change_password "libretime" "new-password"
```
:::
```yml
rabbitmq:
# The hostname of the RabbitMQ server, default is localhost
host: localhost
# The port of the RabbitMQ server, default is 5672
port: 5672
# The virtual host of RabbitMQ server, default is /libretime
vhost: /libretime
# The username of the RabbitMQ user, default is libretime
user: libretime
# The password of the RabbitMQ user, default is libretime
password: some_random_generated_secret!
```
In order to apply the changes made in this section, please restart the following services:
```
libretime-api
libretime-analyzer
libretime-celery
libretime-playout
```
## Playout
The `playout` section configure anything related to the playout service.
```yml
playout:
# Liquidsoap connection host, default is localhost
liquidsoap_host: localhost
# Liquidsoap connection port, default is 1234
liquidsoap_port: 1234
# The format for recordings, allowed values are ogg,mp3, default is ogg
record_file_format: ogg
# The bitrate for recordings, default is 256
record_bitrate: 256
# The samplerate for recordings, default is 44100
record_samplerate: 44100
# The number of channels for recordings, default is 2
record_channels: 2
# The sample size for recordings, default is 16
record_sample_size: 16
```
In order to apply the changes made in this section, please restart the following services:
```
libretime-playout
```
## LDAP
The `ldap` section provide additional configuration for the authentication mechanism defined in `general.auth`, please see the [custom authentication documentation](../custom-authentication.md) for more details.
```yml
ldap:
# Hostname of LDAP server
hostname: ldap.example.org
# Complete DN of user used to bind to LDAP
binddn: "uid=libretime,cn=sysaccounts,cn=etc,dc=int,dc=example,dc=org"
# Password for binddn user
password: hackme
# Domain part of username
account_domain: INT.EXAMPLE.ORG
# Base search DN
basedn: "cn=users,cn=accounts,dc=int,dc=example,dc=org"
# Name of the uid field for searching. Usually uid, may be cn
filter_field: uid
# Map user types to LDAP groups. Assign user types based on the group of a given user
# Key format is groupmap_*
groupmap_superadmin: "cn=superadmin,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
groupmap_admin: "cn=admin,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
groupmap_program_manager: "cn=program_manager,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
groupmap_host: "cn=host,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
groupmap_guest: "cn=guest,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
```

View file

@ -0,0 +1,195 @@
---
title: Install
sidebar_position: 10
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';
import vars from '@site/vars';
This guide walk you though the steps required to install LibreTime on your system.
:::tip
If you are coming from **Airtime**, please follow the [Airtime migration guide](./migrate-from-airtime.md).
:::
You can install LibreTime using the one of the following methods:
- [:rocket: Using the installer](#using-the-installer)
- :construction: Using Ansible
#### Minimum system requirements
- One of the following Linux distributions
- Ubuntu [current LTS](https://wiki.ubuntu.com/Releases).
[Note Ubuntu 22.04 LTS is not yet supported](https://github.com/libretime/libretime/issues/1845)
- Debian [current stable](https://www.debian.org/releases/)
- 1 Ghz Processor
- 2 GB RAM recommended (1 GB required)
- A static external IP address ([How to setup a static ip using Netplan](../tutorials/setup-a-static-ip-using-netplan.md))
:::warning
Make sure that you have configured a **firewall** and it's not blocking connection to the desired ports.
- [How to setup a firewall using UFW](../tutorials/setup-a-firewall-using-ufw.md)
LibreTime requires the following default ports to be open:
- `80` for the web interface,
- `8000` for the Icecast streams,
- `8001` and `8002` for the live stream input endpoint.
:::
## Using the installer
The installer is shipped in the released tarballs or directly in the project repository.
### Download
You can either download the latest released tarball or clone the repository.
<Tabs>
<TabItem label="Release tarball" value="tarball" default>
Download the [latest released](https://github.com/libretime/libretime/releases) tarball from Github.
Or directly from the command-line:
<CodeBlock language="bash">
wget https://github.com/libretime/libretime/releases/download/{vars.version}/libretime-{vars.version}.tar.gz
</CodeBlock>
And extract the tarball:
<CodeBlock language="bash">
tar -xvf libretime-{vars.version}.tar.gz && cd libretime
</CodeBlock>
</TabItem>
<TabItem label="Git repository" value="git">
Clone the project repository:
```bash
git clone https://github.com/libretime/libretime
cd libretime
```
:::caution
Don't use the https://github.com/libretime/libretime-debian-packaging repository, it is only used to create LibreTime packages.
:::
:::info
When upgrading, you should clean the local repository, pull the latest changes and finally check out the desired version:
```bash
cd libretime
git clean -xdf
git pull
```
:::
And checkout the latest version:
<CodeBlock language="bash">
git checkout {vars.version}
</CodeBlock>
</TabItem>
</Tabs>
### Run the installer
Install LibreTime with the recommended options, be sure to replace `PUBLIC_URL` with the public url of your installation,
for example `https://libretime.example.com` or `http://192.168.10.100:80`:
```bash
sudo ./install PUBLIC_URL
```
:::caution
When upgrading be sure to run the installer using the same arguments you used during the initial install.
:::
If you need to change some configuration, the install script can be configured using flags or environment variables. Changing the listening port of LibreTime or whether you want to install some dependency by yourself, you could run the following:
```bash
# Install LibreTime on your system with the following tweaks:
# - do not install the liquidsoap package (remember to install liquidsoap yourself)
# - set the listen port to 8080
# - do not run the PostgreSQL setup (remember to setup PostgreSQL yourself)
sudo \
LIBRETIME_PACKAGES_EXCLUDES='liquidsoap' \
./install \
--listen-port 8080 \
--no-setup-postgresql \
https://libretime.example.com
```
You can persist the install configuration in a `.env` file next to the install script. For example, the above command could be persisted using the `.env` file below, and you should be able to run the install script without arguments:
```
LIBRETIME_PACKAGES_EXCLUDES='liquidsoap'
LIBRETIME_LISTEN_PORT='8080'
LIBRETIME_SETUP_POSTGRESQL=false
LIBRETIME_PUBLIC_URL='https://libretime.example.com'
```
:::note
The install script will use randomly generated passwords to create the PostgreSQL user, RabbitMQ user and to update the default Icecast passwords. Those passwords will be saved to the configuration files.
:::
:::info
By default, the install script will not restart any service for you, this is to prevent unwanted restarts on production environment. To let the install script restart the services, you need to pass the `--allow-restart` flag.
:::
Feel free to run `./install --help` to get more details.
#### Using hardware audio output
If you plan to output analog audio directly to a mixing console or transmitter, the user running LibreTime needs to be added to the `audio` user group using the command below:
```bash
sudo adduser libretime audio
```
### Setup
Once the installation is completed, edit the [configuration file](./configuration.md) at `/etc/libretime/config.yml` to fill required information and to match your needs.
Next, run the following commands to setup the database:
```bash
sudo -u libretime libretime-api migrate
```
Synchronize the new Icecast passwords into the database:
```bash
sudo libretime-api set_icecast_passwords --from-icecast-config
```
Finally, start the services, and check that they are running properly using the following commands:
```bash
sudo systemctl start libretime.target
sudo systemctl --all --plain | grep libretime
```
Once completed, it's recommended to [install a reverse proxy](./reverse-proxy.md) to setup SSL termination and secure your installation.

View file

@ -0,0 +1,40 @@
---
title: Migrate from Airtime
sidebar_position: 90
---
This guide walk you though the steps required to migrate your data from Airtime to LibreTime.
:::info
Airtime **linked files** and **watched folders** features are either deprecated or not working in LibreTime.
:::
LibreTime dropped support for Ubuntu 16.04, which is the last supported version of Ubuntu that Airtime supports.
## Make a backup
<!-- TODO: Airtime backup process might be different from the LibreTime one, we might need to write a dedicated backup guide here. -->
Follow [the backup guide](../backup.md) to make a backup of your current Airtime installation.
## Install
Install LibreTime on a new system by [running the installer](./install.md#run-the-installer), and **don't run the setup tasks**.
## Restore the backup
Restore [the Airtime backup](../backup.md#restore) on the newly installed LibreTime server.
You have to restore the **database**, the **files storage** and the **configuration files**.
## Update the configuration files
Update the configuration file to match the new configuration schema and update any changed values. See the [configuration](./configuration.md) documentation for more details.
Edit the Icecast password in `/etc/icecast2/icecast.xml` to reflect the password used in Airtime.
## Finish
Restart the LibreTime services and navigate to the LibreTime web-page.

View file

@ -0,0 +1,150 @@
---
title: Reverse proxy
sidebar_position: 30
---
This guide walk you though the steps required to setup a reverse proxy in front of LibreTime.
Setting a reverse proxy in front of LibreTime is recommended, it prevents LibreTime to be
open to the Internet, adds security by enabling `https` and let's you manage your certificates in
a single place.
:::warning
The current input and output streams are Icecast based protocols and does not support being behind a reverse proxy. **Do not attempt** to [reverse proxy Icecast](#icecast) or the Liquidsoap harbor inputs.
Modern protocols such as [HLS](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) and [SRT](https://en.wikipedia.org/wiki/Secure_Reliable_Transport) will be implement in the future to fix those limitations.
:::
Below is a schema that illustrate the goals when setting up a reverse proxy in front of LibreTime:
```mermaid
flowchart TD
internet[Internet]
subgraph internal[Your system or private network]
libretime[LibreTime service, listen on :8080]
icecast[Icecast service, listen on :8000]
liquidsoap[Liquidsoap service, listen on :8001 and 8002]
subgraph proxy[Your reverse proxy]
front_http[Listen on :80]
front_https[Listen on :443]
front_http -.-> |Redirect to https| front_https
router[Router]
front_https --> |Terminate https| router
end
router --> |If hostname is radio.example.com| libretime
end
internet ==> front_http
internet ==> front_https
internet ==> icecast
internet ==> liquidsoap
```
## Prerequisites
You need a domain name (`radio.example.com`) and a `tls` certificate for that domain. You can get certificates from Let's Encrypt by using [Certbot](https://certbot.eff.org/).
You need to identify the location of the services that should be exposed to the public:
- the LibreTime web server (usually `localhost:8080`, for documentation clarity we use `libretime:8080`).
:::info
If LibreTime is running on the same host as the reverse proxy, you need to change the LibreTime web server default listening port because the reverse proxy needs to listen on the `80`and `443` ports.
:::
:::caution
Be sure that your firewall and network allows communications from the reverse proxy to the services. You can use `ping`, `telnet` and `curl` to check that communication is working.
:::
## Install a reverse proxy
### Apache
:::info
You follow one of these guides to configure Apache with a Let's Encrypt certificate.
- [How To Secure Apache with Let's Encrypt on Ubuntu 20.04](https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-20-04)
:::
:construction:
### Nginx
:::info
You follow one of these guides to configure Nginx with a Let's Encrypt certificate.
- [How To Secure Nginx with Let's Encrypt on Ubuntu 20.04](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-20-04)
:::
Once you installed nginx and retrieved the required certificates, you can configure the reverse proxy to work with LibreTime.
Paste the following configuration in `/etc/nginx/sites-available/libretime.conf` and be sure to replace:
- `radio.example.com` with your own station url,
- `libretime:8080` with the location of your LibreTime web server;
```nginx
server {
listen 80;
server_name radio.example.com;
location / {
rewrite ^ https://$server_name$request_uri? permanent;
}
}
server {
listen 443 ssl;
server_name radio.example.com;
ssl_certificate /etc/letsencrypt/live/radio.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/radio.example.com/privkey.pem;
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_pass http://libretime:8080/;
}
}
```
Enable the nginx configuration and restart nginx using the commands below:
```bash
ln -s /etc/nginx/sites-available/libretime.conf /etc/nginx/sites-enabled/
sudo systemctl restart nginx
```
## Icecast
:::warning
If you attempt to listen an insecure Icecast stream on a secure website, a
[mixed content error](https://support.mozilla.org/en-US/kb/mixed-content-blocking-firefox)
will be raised by your browser and should prevent your player from listening to the stream.
You follow one of these guides to configure a secure Icecast server with a Let's Encrypt certificate.
- [Icecast HTTPS/SSL with Lets Encrypt](https://mediarealm.com.au/articles/icecast-https-ssl-setup-lets-encrypt/)
:::

View file

@ -0,0 +1,78 @@
---
title: Upgrade
sidebar_position: 80
---
This guide walk you though the steps required to upgrade LibreTime.
:::tip
You should always have proper backups and a rollback scenario in place before updating. If the update does not go smoothly, it may cause significant downtime, so you should always have a fallback system available during the update to ensure **broadcast continuity**.
:::
## Stop the services
Run the following commands to stop the services:
```bash
sudo systemctl stop libretime.target
# Or
sudo systemctl stop libretime-analyzer.service
sudo systemctl stop libretime-api.service
sudo systemctl stop libretime-celery.service
sudo systemctl stop libretime-liquidsoap.service
sudo systemctl stop libretime-playout.service
```
## Make a backup
Follow [the backup guide](../backup.md) to make an extra backup of your installation and prepare a rollback scenario in case of accidental data loss during the upgrade process.
## Apply upgrade instructions
Be sure to carefully read **all** the [releases notes](../../releases/README.md), from your current version to the targeted version, to apply upgrade or breaking changes instructions to your installation.
:::caution
You might need to run steps before and after the install procedure. Be sure to follow these steps thoroughly.
:::
## Install the new version
Follow [the install guide](./install.md#download) to download and install the new version, and re-run the `./install` script with the same arguments you used during the initial install.
## Apply migrations
Run the following command to apply the database migrations:
```bash
sudo -u libretime libretime-api migrate
```
## Restart the services
Restart all the services to make sure all the changes are applied.
```bash
sudo systemctl restart libretime.target
```
## Verify
Verify that all the services are still running after the install process:
```bash
sudo systemctl --all --plain | egrep 'libretime|nginx|php.*-fpm'
```
Verify for any error in the logs after the install process:
```bash
sudo tail -f -n 100 "/var/log/syslog" | grep "libretime-"
```
Log into the interface and verify for any error after the install process.
If you encounter issues with the new interface, you may need to clear your web browser's cache.