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

docs: rename setup to install

Browse source
This commit is contained in:
jo 2023-04-21 11:50:37 +02:00 • committed by Kyle Robbertze
parent 8052622e69
commit ff03dad9a8
10 changed files with 13 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

316
docs/admin-manual/install/README.md Normal file
View file

@ -0,0 +1,316 @@
---
title: Install
sidebar_position: 00
---
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 docker-compose](#using-docker-compose)
- [:rocket: Using the installer](#using-the-installer)
- :construction: Using ansible
### Minimum system requirements
- 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.
We recommend installing on one of the following [distribution releases](../../releases/README.md#distributions-releases-support):
- [Debian 11](https://www.debian.org/releases/)
- [Ubuntu 20.04 LTS](https://wiki.ubuntu.com/Releases)
### Before installing
Before installing LibreTime, you need to make sure you operating system is properly configured.
#### Operating system time configuration
Check your operating system time configuration using the following command:
```bash
timedatectl
```
```
Local time: Fri 2022-08-05 12:43:39 CEST
Universal time: Fri 2022-08-05 10:43:39 UTC
RTC time: Fri 2022-08-05 10:43:40
Time zone: Europe/Berlin (CEST, +0200)
System clock synchronized: yes
NTP service: active
RTC in local TZ: no
```
Make sure that your time zone is properly configured, if not you can set it using the [`timedatectl set-timezone` command](https://www.freedesktop.org/software/systemd/man/timedatectl.html#set-timezone%20%5BTIMEZONE%5D).
If the NTP service is inactive, you should consider enabling it using the [`timedatectl set-ntp` command](https://www.freedesktop.org/software/systemd/man/timedatectl.html#set-ntp%20%5BBOOL%5D).
### 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's 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.
:::
:::warning
To update the LibreTime nginx configuration file, for example to change the `--listen-port`, make sure to add the `--update-nginx` flag to allow overwriting the existing configuration file.
:::
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:
# - don't install the liquidsoap package (remember to install liquidsoap yourself)
# - set the listen port to 8080
# - don't 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.
:::
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
```
Finally, start the services, and check that they're running properly using the following commands:
```bash
sudo systemctl start libretime.target
sudo systemctl --all --plain | grep libretime
```
Next, continue by [configuring your installation](#configure).
## Using docker-compose
### Download
Pick the version you want to install:
<CodeBlock language="bash">
echo LIBRETIME_VERSION="{vars.version}" > .env
</CodeBlock>
Download the docker-compose files from the repository:
```bash
# Load LIBRETIME_VERSION variable
source .env
wget "https://raw.githubusercontent.com/libretime/libretime/$LIBRETIME_VERSION/docker-compose.yml"
wget "https://raw.githubusercontent.com/libretime/libretime/$LIBRETIME_VERSION/docker/nginx.conf"
wget "https://raw.githubusercontent.com/libretime/libretime/$LIBRETIME_VERSION/docker/config.yml"
```
### Setup
Once the files are downloaded, generate a set of random passwords for the different docker services used by LibreTime:
```bash
echo "# Postgres
POSTGRES_PASSWORD=$(openssl rand -hex 16)
# RabbitMQ
RABBITMQ_DEFAULT_PASS=$(openssl rand -hex 16)
# Icecast
ICECAST_SOURCE_PASSWORD=$(openssl rand -hex 16)
ICECAST_ADMIN_PASSWORD=$(openssl rand -hex 16)
ICECAST_RELAY_PASSWORD=$(openssl rand -hex 16)" >> .env
cat .env
```
:::info
You can find more details in the `docker-compose.yml` file or on the external services docker specific documentation:
- [Postgres](https://hub.docker.com/_/postgres)
- [RabbitMQ](https://hub.docker.com/_/rabbitmq)
- [Icecast](https://github.com/libretime/icecast-docker#readme)
:::
Next, edit the [configuration file](../configuration.md) at `./config.yml` to set the previously generated passwords, fill required information, and to match your needs.
:::info
The `docker/config.yml` configuration file you previously downloaded already contains specific values required by the container setup, you shouldn't change them:
```yaml
database:
host: "postgres"
rabbitmq:
host: "rabbitmq"
playout:
liquidsoap_host: "liquidsoap"
liquidsoap:
server_listen_address: "0.0.0.0"
stream:
outputs:
.default_icecast_output:
host: "icecast"
```
:::
Next, run the following commands to setup the database:
```bash
docker-compose run --rm api libretime-api migrate
```
Finally, start the services, and check that they're running properly using the following commands:
```bash
docker-compose up -d
docker-compose ps
docker-compose logs -f
```
Next, continue by [configuring your installation](#configure).
## Configure
Once the setup is completed, log in the interface (with the default user `admin` and password `admin`), and make sure to edit the project settings (go to **Settings** > **General**) to match your needs. Important settings are:
- First day of the week
## Next
Once completed, it's recommended to [install a reverse proxy](./reverse-proxy.md) to setup SSL termination and secure your installation.

58
docs/admin-manual/install/migrate-from-airtime.md Normal file
View file

@ -0,0 +1,58 @@
---
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
### Backup the configuration
On common setups, you need to backup the entire `/etc/airtime` folder.
### Backup the database
You need to backup the PostgreSQL database, which holds the entire data of your installation.
Here is an example to dump your PostgreSQL database:
```bash
sudo -u postgres pg_dump --file=airtime.sql airtime
```
Please read the `pg_dump` usage for additional details.
### Backup the storage
You need to backup the entire file storage, which holds all the files of your installation.
The path to your storage was defined during the installation process, the default storage path is `/srv/airtime/stor`.
## Install
Install LibreTime on a new system by [running the installer](./README.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.

150
docs/admin-manual/install/reverse-proxy.md Normal file
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 doesn't support being behind a reverse proxy. **Don't 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 Let’s Encrypt](https://mediarealm.com.au/articles/icecast-https-ssl-setup-lets-encrypt/)
:::

96
docs/admin-manual/install/upgrade.md Normal file
View file

@ -0,0 +1,96 @@
---
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 doesn't go smoothly, it may cause significant downtime, so you should always have a fallback system available during the update to ensure **broadcast continuity**.
:::
:::info
You may upgrade LibreTime by migrating to a new server. This is probably the cleanest way if you are coming from [Airtime](./migrate-from-airtime.md), if you wish to upgrade the underlying system, or if you want to skip multiple upgrade procedures.
:::
## 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-liquidsoap.service
sudo systemctl stop libretime-playout.service
sudo systemctl stop libretime-worker.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.
:::danger
If you are migrating LibreTime to a new server, you must **not** apply the upgrade procedure.
:::
:::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](./README.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.
:::caution
If you are migrating LibreTime to a new server, you must **stop before the [setup tasks](./README.md#setup)** and [restore the backups](../backup.md#restore-a-backup) on the new server.
:::
## 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.