Congegni/sintonia
7
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: update structure and create links between pages (#1611)

Browse source 
* docs: rework files structure

* rewrite documentation entrypoint

* update category files and use yml

* add manuals entry page

* update admin-manual titles and page order

* create releases sections

* move ssl configuration to reverse proxy

* docs: update website vars and links

* update release note codeblock syntax key

* resurect troubleshooting guide

* Update freeipa custom auth documentation

* add notice about the state of the documentation

* update the backup documentation

* tmp: allow to deploy the website for preview

* Don't use require.resolve for plugins

* Update the main page link dest

* update development environment title

* rewrite the install/upgrade/migrate as guides

* update website docs sections links

* Fix urls

* move release note to documentation

* move home links to vars files

* tmp: update deploy url

* add react to tsconfig to handle jsx linting

* fix: replace absolute url to relative path to files

* tmp: allow CI Website dpeloy on working branch

* Update release note title

* use default syntax highlighting theme

* update the troubleshooting guide

* Wording

* use CodeBlock components

* Better prose

* remove api_client config section

* fix prose errors

* update import prefix for vars file

* reroder docs manuals links

* use sentence capitalization for page titles

* Wording

* missing word

* Update note about syslog log file

* wording
This commit is contained in:
Jonas L 2022-02-21 08:16:54 +01:00 • committed by GitHub
parent 5769821995
commit 3ec85d7821
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
107 changed files with 682 additions and 512 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/admin-manual/setup/_category_.yml Normal file
View file

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

178
docs/admin-manual/setup/configuration.md Normal file
View file

@ -0,0 +1,178 @@
---
title: Configuration
sidebar_position: 20
---
The streaming host configuration for LibreTime is shown in the file `/etc/airtime/liquidsoap.cfg` which is automatically generated by the **Streams** page, found on the **System** menu of the LibreTime administration interface. For this reason, you would not normally edit the streaming configuration manually, as any changes are likely to be overwritten by the administration interface.
## Database and RabbitMQ hosts
Optionally, you may wish to edit the file `/etc/airtime/airtime.conf` to set the PostgreSQL database host, and the username and password to connect to the database with.
You can also set options for RabbitMQ messaging and the LibreTime server in this file, although you shouldn't normally need to adjust the defaults unless you are running a large LibreTime system distributed across multiple servers. To run the LibreTime server in demo mode, which changes the greeting on the login page and prevents user accounts from being created or modified, set the value of _demo_ to 1.
```ini title="/etc/airtime/airtime.conf"
[database]
host = localhost
port = 5432
name = libretime
user = libretime
password = libretime
[rabbitmq]
host = 127.0.0.1
port = 5672
user = airtime
password = XXXXXXXXXXXXXXXXXXXX
vhost = /airtime
[general]
api_key = XXXXXXXXXXXXXXXXXXXXX
web_server_user = www-data
airtime_dir = /usr/share/airtime
base_url = libretime.example.com
base_port = 80
base_dir = /
cache_ahead_hours = 1
[monit]
monit_user = guest
monit_password = airtime
[demo]
demo = 0
```
Save and close the file then, run the following commands to restart LibreTime's services:
```bash
sudo systemctl restart libretime-liquidsoap
sudo systemctl restart libretime-playout
sudo systemctl restart libretime-celery
sudo systemctl restart libretime-analyzer
```
## Apache max file size configuration
By default, the maximum upload file size is 40 MB, which may not be large enough for some stations, especially if they're uploading prerecorded shows. The setting for this is located in `/etc/apache2/sites-available/airtime.config`. Search for and update the following in megabytes:
```ini
; Maximum allowed size for uploaded files.
upload_max_filesize = 40M
; Must be greater than or equal to upload_max_filesize
post_max_size = 40M
```
For quick reference, 1024 MB = 1 GB and 2048 MB = 2 GB, but most should be okay with rounding to the nearest thousand. After updating the config file, restart Apache with `sudo systemctl restart apache2`.
## Playout settings
Settings for pypo, the playout engine used by LibreTime, are found in the file `/etc/airtime/airtime.conf`. After making changes to this file, run `sudo systemctl restart libretime-playout`.
```ini
############################################
# pypo - configuration #
############################################
# Set the type of client you are using.
# Currently supported types:
# 1) "obp" = Open Broadcast Platform
# 2) "airtime"
#
api_client = airtime
############################################
# Cache Directories #
# *include* trailing slash !! #
############################################
cache_dir = /var/tmp/airtime/pypo/cache/
file_dir = /var/tmp/airtime/pypo/files/
tmp_dir = /var/tmp/airtime/pypo/tmp/
############################################
# Setup Directories #
# Do *not* include trailing slash !! #
############################################
cache_base_dir = /var/tmp/airtime/pypo
bin_dir = /usr/lib/airtime/pypo
log_base_dir = /var/log/airtime
pypo_log_dir = /var/log/airtime/pypo
liquidsoap_log_dir = /var/log/airtime/pypo-liquidsoap
############################################
# Liquidsoap settings #
############################################
ls_host = 127.0.0.1
ls_port = 1234
############################################
# RabbitMQ settings #
############################################
rabbitmq_host = localhost
rabbitmq_user = airtime
rabbitmq_password = XXXXXXXXXXXXXXXXXXXX
rabbitmq_vhost = /airtime
############################################
# pypo preferences #
############################################
# Poll interval in seconds.
#
# This will rarely need to be changed because any schedule changes are
# automatically sent to pypo immediately.
#
# This is how often the poll script downloads new schedules and files from the
# server in the event that no changes are made to the schedule.
#
poll_interval = 3600# in seconds.
# Push interval in seconds.
#
# This is how often the push script checks whether it has something new to
# push to liquidsoap.
#
# It's hard to imagine a situation where this should be more than 1 second.
#
push_interval = 1# in seconds
# 'pre' or 'otf'. 'pre' cues while playlist preparation
# while 'otf' (on the fly) cues while loading into ls
# (needs the post_processor patch)
cue_style = pre
```
## RabbitMQ hostname changes
If the Airtime logs indicate failures to connect to the RabbitMQ server, such as:
```
2013-10-31 08:21:11,255 ERROR - [pypomessagehandler.py : main() : line
99] - Error connecting to RabbitMQ Server. Trying again in few seconds
2013-10-31 08:21:11,255 ERROR - \[pypomessagehandler.py : main() : line 99\] - Error connecting to RabbitMQ Server. Trying again in few seconds - See more at: https://forum.sourcefabric.org/discussion/16050/#sthash.W8OJrNFm.dpuf
```
but the RabbitMQ server is running normally, this error might be due to a change in the server's hostname since LibreTime installation. Directory names under `/var/lib/rabbitmq/mnesia/` indicate that RabbitMQ's database files are organized according to the hostname of the server (ex. `rabbit@airtime`) where the hostname is `airtime.example.com`. If the hostname has changed, it may be necessary to reconfigure RabbitMQ manually, as follows:
1. Delete the files in `/var/lib/rabbitmq/mnesia/`
```bash
sudo rm -r /var/lib/rabbitmq/mnesia/*
```
2. Restart RabbitMQ:
```bash
sudo systemctl restart rabbitmq-server
```
3. Enter the following commands to set up authentication and grant permissions. The _rabbitmqctl add_user_ command requires the RabbitMQ password from the /etc/airtime/airtime.conf file as an argument. The _rabbitmqctl set_permissions_ command should be entered on one line, with the list of Airtime services repeated three times:
```bash
rabbitmqctl add_vhost /airtime
rabbitmqctl add_user airtime XXXXXXXXXXXXXXXXXXXX
rabbitmqctl set_permissions -p /airtime airtime
"airtime-pypo|pypo-fetch|airtime-analyzer|media-monitor"
"airtime-pypo|pypo-fetch|airtime-analyzer|media-monitor"
"airtime-pypo|pypo-fetch|airtime-analyzer|media-monitor"
```

144
docs/admin-manual/setup/install.md Normal file
View file

@ -0,0 +1,144 @@
---
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)
- 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))
## 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
```
And checkout the latest version:
<CodeBlock language="bash">
git checkout {vars.version}
</CodeBlock>
</TabItem>
</Tabs>
### Run the installer
Install LibreTime with the recommended options:
```bash
sudo ./install -fiap
```
Additional options can be listed with the following command:
```bash
./install --help
```
Once the installation is completed, open [http://localhost:80](http://localhost:80) to complete the [setup wizard](#setup-wizard).
:::note
- If installed on a remote device, make sure to replace `localhost` with your server's remote address.
- If installed with a custom port, make sure to replace `80` with the custom port.
:::
:::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 ports to be open:
- `80` for the web interface,
- `8000` for the Icecast streams,
- `8001` and `8002` for the live stream input endpoint.
Consider putting your installation behind a [reverse proxy](./reverse-proxy.md) to increase the security.
:::
#### Using hardware audio output
If you plan to output analog audio directly to a mixing console or transmitter, the user running LibreTime (by default `www-data`) needs to be added to the `audio` user group using the command below:
```bash
sudo adduser www-data audio
```
### Setup wizard
The setup wizard walk you through the rest of the installation process.
#### Changing default passwords
It's recommended that you change the passwords prompted in the setup wizard. Be sure to apply the changes on the server before going to any next step.
You can change the default PostgreSQL user password using:
```bash
sudo -u postgres psql -c "ALTER USER airtime PASSWORD 'new-password';"
```
You can change the default RabbitMQ user password using:
```bash
sudo rabbitmqctl change_password "airtime" "new-password"
```
Once completed, it's recommended to [install a reverse proxy](./reverse-proxy.md) to setup SSL termination and secure your installation.

40
docs/admin-manual/setup/migrate-from-airtime.md Normal file
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 following the [install guide](./install.md), and **don't run the setup wizard**.
## 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.

125
docs/admin-manual/setup/reverse-proxy.md Normal file
View file

@ -0,0 +1,125 @@
---
title: Reverse proxy
sidebar_position: 30
---
In some deployments, the LibreTime server is deployed behind a reverse proxy,
for example in containerization use-cases such as Docker and LXC. LibreTime
makes extensive use of its API for some site features, which causes
[Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
to occur. By default, CORS requests are blocked by your browser and the origins
need to be added to the **Allowed CORS URLs** block in
[**General Settings**](../../user-manual/settings.md). These origins should include any
domains that are used externally to connect to your reverse proxy that you
want handled by LibreTime. These URLS can also be set during the first run configuration
that's displayed when you first install LibreTime
### Reverse proxy basics
A reverse proxy allows the LibreTime server to not be connected to the open internet. In
this configuration, it's rather behind another server that proxies traffic to it from
users. This provides some advantages in the containerization space, as this means that
the containers can be on their own internal network, protected from outside access.
A reverse proxy also allows SSL to be terminated in a single location for multiple sites.
This means that all your traffic to the proxy from clients is encrypted, but the reverse
proxy's traffic to the containers on the internal network isn't. All the SSL certificates
live on the reverse proxy and can be renewed there instead of on the individual
containers.
### Setup
For SSL redirection to work, you need two domains: one for LibreTime and one for Icecast.
Here, these will be `libretime.example.com` and `icecast.example.com`.
You require two VMs, servers or containers. Alternatively the reverse proxy can
be located on the server, proxying connections to containers also on the host. Setting up
a containerization environment is beyond the scope of this guide. It assumes that you have
Nginx set up on `localhost` and LibreTime will be installed on `192.168.1.10`. You will need root
access on both. `192.168.1.10` also needs to be able to be accessed from `localhost`
(`ping 192.168.1.10` on `localhost`).
On `192.168.1.10`, install LibreTime as described in the [install guide](./install.md). Once it has installed, replace `<hostname>localhost</hostname>` in
`/etc/icecast2/icecast.xml` with the following:
```xml
<hostname>icecast.example.com</hostname>
```
This is the hostname that people listening to your stream will connect to and what
LibreTime will use to stream out to them. You will then need to restart Icecast using `sudo systemctl restart icecast2`.
On `localhost`, run the following:
```bash
cat << EOF | sudo tee /etc/nginx/sites-available/libretime.conf
server {
listen 80;
server_name libretime.example.com;
location / {
rewrite ^ https://$server_name$request_uri? permanent;
}
}
server {
listen 443 ssl;
server_name libretime.example.com;
ssl_certificate /etc/letsencrypt/live/libretime.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/libretime.example.com/privkey.pem;
add_header Strict-Transport-Security "max-age=15552000;";
add_header X-Frame-Options "SAMEORIGIN";
client_max_body_size 512M;
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://192.168.1.10/;
}
}
EOF
```
This Nginx configuration ensures that all traffic uses SSL to the reverse proxy, and
traffic is proxied to `192.168.1.10`.
Next, the SSL certificate needs to be generated and the site activated.
```
sudo apt install certbot
sudo systemctl stop nginx
sudo certbot certonly -d libretime.example.com -a standalone
sudo systemctl start nginx
```
You can now go to `https://libretime.example.com` and go
through the installer. On `General Settings`, you need to change the Webserver Port to
`443` and add the following CORS URLs:
```
https://libretime.example.com
http://libretime.example.com
https://localhost
http://localhost
```
Finally, the configuration file needs updating. Under `[general]`, `force_ssl`
needs to be set to true:
```ini
[general]
...
force_ssl = true
```
## SSL Configuration
To increase the security of your server, you can enable encrypted access to the LibreTime administration interface, and direct your users towards this more secure login page. The main advantage of using this encryption is that your remote users' login names and passwords are not sent in plain text across the public Internet or untrusted local networks, such as shared Wi-Fi access points.
## Deploying a certificate with Certbot
One of the fastest, easiest, and cheapest ways to get an SSL certificate is through [Certbot](https://certbot.eff.org/), as created by the
Electronic Frontier Foundation. To use Certbot, your LibreTime installation must be open to the internet on port 80.
Follow [Certbot's documentation](https://certbot.eff.org/instructions) for your OS and webserver to install an SSL certificate. You'll need to renew the certificate every 90 days to keep your installation secure.
## Mixed encrypted and unencrypted content
Whether your certificate is self-signed or not, you will see browser security warnings whenever a https:// page is delivering unencrypted content, such as the stream from an Icecast server. In Firefox, an exclamation mark icon is displayed in the address bar of the **Listen** pop-up.

45
docs/admin-manual/setup/upgrade.md Normal file
View file

@ -0,0 +1,45 @@
---
title: Upgrade
sidebar_position: 80
---
This guide walk you though the steps required to upgrade LibreTime.
:::tip
You should always have a fallback system available during the upgrade to ensure **broadcast continuity**.
:::
#### Make a backup
Follow [the backup guide](../backup.md) to make an extra backup of your installation in case of accidental data loss during
the upgrade process.
#### Install the new version
Follow [the install guide](./install.md) to download and install the new version.
#### Verify
Verify that all the services are still running after the install process:
```bash
sudo systemctl status \
libretime-analyzer \
libretime-api \
libretime-celery \
libretime-liquidsoap \
libretime-playout \
apache2
```
Verify for any error in the logs after the install process:
```bash
sudo tail -n 20 /var/log/libretime/**/*.log
```
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.