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

docs: rework docs into the new website

Browse source 
- multipass docs moved to local-dev.md
- add documentation to website
- rework fogotten files
- disable fogotten files

Co-authored-by: Zachary Klosko <zklosko@users.noreply.github.com>
This commit is contained in:
jo 2022-02-09 09:37:52 +01:00 • committed by Jonas L
parent 2fa10793ec
commit 6d9e7a6765
39 changed files with 698 additions and 721 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/getting-started/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "Getting Started",
"position": 2
}

29
docs/getting-started/default-passwords.md
View file

@ -1,10 +1,9 @@
---
title: How To Change Default Passwords
layout: article
category: admin
title: Change Default Passwords
sidebar_position: 3
---
### Libretime
## Libretime
To change the password of the current user:
@ -18,7 +17,7 @@ To change the password for a different user (requires _Administrator_ privileges
2. Go to **Settings** > **Manage Users**
3. Select the user, enter the new password twice, and click **Save**
### PostgreSQL
## PostgreSQL
Two of the most important passwords that should be changed _immediately_ after installation
are the passwords used by the PostgreSQL database.
@ -32,15 +31,13 @@ It is strongly recommended that you do this before exposing your server to the i
4. If all is successful, logout of PostgreSQL with `\q`, go back to _/etc/airtime/airtime.conf_ to edit the password
in the config file, and restart all services mentioned in the previous section.
### Icecast
## Icecast
Random passwords are generated for Icecast during the installation. To look up and change the passwords, look in the file below.
`/etc/icecast2/icecast.xml`
Random passwords are generated for Icecast during the installation. To look up and change the passwords, edit `/etc/icecast2/icecast.xml`.
Replace the admin and _changeme_ fields below.
```
```xml
<authentication>
<!-- Sources log in with username 'source' -->
<source-password>changeme</source-password>
@ -52,19 +49,15 @@ Replace the admin and _changeme_ fields below.
</authentication>
```
Then, restart your icecast2 service.
```
sudo systemctl restart icecast2
```
Then, restart your icecast2 service with `sudo systemctl restart icecast2`.
> Note: If you change the source password, you may need to manually configure Libretime to use the new password: go to **Settings** > **Streams**, set the streaming server to **Custom** and fill out the **Additional Options** below Stream 1.
### Rabbitmq
## RabbitMQ
To change the default password for Rabbitmq, run the following command
To change the default password for RabbitMQ, run the following command
```
```bash
sudo rabbitmqctl change_password airtime newpassword
```

48
docs/getting-started/install.md
View file

@ -1,8 +1,6 @@
---
title: Install
layout: article
category: install
permalink: /install
title: Installation
sidebar_position: 1
---
## Minimum System Requirements
@ -12,15 +10,11 @@ permalink: /install
- Debian [current stable](https://www.debian.org/releases/)
- 1 Ghz Processor
- 2 GB RAM recommended (1 GB required)
- Wired internet connection and static IP address for on-prem install
[DigitalOcean](https://www.digitalocean.com/pricing/#Compute) and [Linode](https://www.linode.com/pricing/#row--compute)
have similar plans that meet Cloud Install requirements. Both plans cost $10/month.
- A static IP address for your server
## Preparing the server
Configure the server to have a static IP address by modifying the Netplan configuration.
If you're using a cloud VM, you likely already have a static IP address. Check with your provider to confirm this.
```
cd /etc/netplan && ls # find the netplan filename
@ -29,10 +23,21 @@ sudo nano ##-network-manager-all.yaml
If the Netplan configuration is empty, fill in the file with the example below. Otherwise,
input the IP address reserved for the server in `xxx.xxx.xxx.xxx/yy` format, the gateway (the IP address
of your router), and the DNS nameserver. If you don't have a nameserver on your network,
feel free to use Cloudflare's: `1.1.1.1` and `1.0.0.1`. In this File is "Tab" not allowed.
of your router), and your DNS server's address.
```
:::tip
Don't have a DNS server of your own? You can use a public DNS server like Google (`8.8.8.8`) or Cloudflare (`1.1.1.1`), or input your router's address in most cases.
:::
:::caution
Do not use tabs in YAML files. Use two spaces to indent instead.
:::
```yaml title="Netplan configuration on Ubuntu"
network:
version: 2
renderer: networkd
@ -48,18 +53,20 @@ After the netplan file has been saved, run `sudo netplan apply` to apply changes
Next, configure Ubuntu's firewall by running:
```
```bash
sudo ufw enable
sudo ufw allow 22,80,8000/tcp
```
:::info
Unblock ports 8001 and 8002 if you plan to use LibreTime's Icecast server to broadcast livestreams without an external Icecast server acting as a repeater.
```
```bash
sudo ufw allow 8001,8002/tcp
```
> If needed, instructions for setting up a reverse proxy can be found [here](/docs/reverse-proxy).
:::
## Installing LibreTime
@ -67,9 +74,10 @@ sudo ufw allow 8001,8002/tcp
Installing LibreTime consists of running the following commands in the terminal:
```
```bash
git clone https://github.com/LibreTime/libretime.git
cd libretime
sudo bash install -fiap
```
@ -84,7 +92,7 @@ it is important that the server starts them during the boot process, to cut down
Ubuntu 18.04 uses the `systemctl` command to manage services, so run the following commands to enable all
LibreTime-needed services to run at boot:
```
```bash
sudo systemctl enable libretime-liquidsoap
sudo systemctl enable libretime-playout
sudo systemctl enable libretime-celery
@ -93,7 +101,11 @@ sudo systemctl enable apache2
sudo systemctl enable rabbitmq-server
```
> If an error is returned, try adding `.service` to the end of each command.
:::tip
If an error is returned, try adding `.service` to the end of each command.
:::
## User Permissions

24
docs/getting-started/reverse-proxy.md
View file

@ -1,7 +1,6 @@
---
title: Reverse Proxy
layout: article
category: install
sidebar_position: 5
---
In some deployments, the LibreTime server is deployed behind a reverse proxy,
@ -10,7 +9,7 @@ makes extensive use of its API for some site functionality, 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**](/docs/settings). These origins should include any
[**General Settings**](/docs/guides/settings). These origins should include any
domains that will be 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 is displayed when you first install LibreTime
@ -40,16 +39,7 @@ Nginx set up on `proxy` and LibreTime will be installed on `libretime`. You will
access on both. `libretime` also needs to be able to be accessed from `proxy`
(`ping libretime` on `proxy`).
On `libretime`, install LibreTime as described in the [install guide](/install). In short
this means run the following commands:
```
git clone https://github.com/LibreTime/libretime.git
cd libretime
sudo ./install -fiap
```
Once it has installed, replace `<hostname>localhost</hostname>` in
On `libretime`, install LibreTime as described in the [install guide](/docs/getting-started/install). Once it has installed, replace `<hostname>localhost</hostname>` in
`/etc/icecast2/icecast.xml` with the following:
```
@ -57,15 +47,11 @@ Once it has installed, replace `<hostname>localhost</hostname>` in
```
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:
```
sudo systemctl restart icecast2
```
LibreTime will use to stream out to them. You will then need to restart Icecast using `sudo systemctl restart icecast2`.
On `proxy`, run the following:
```
```bash
cat << EOF | sudo tee /etc/nginx/sites-available/libretime.conf
server {
listen 80;

79
docs/getting-started/set-server-time.md
View file

@ -1,21 +1,20 @@
---
title: Setting the Server Time
layout: article
category: install
sidebar_position: 2
---
Accurate time keeping on your server is vital for LibreTime performance. You can confirm that the date and time of your server are set correctly with the `date` command.
The server should respond with the date, time, time zone and year in a format similar to the following example:
Tue Jul 2 15:08:57 BST 2013
```
Tue Jul 2 15:08:57 BST 2013
```
If the time on your server is wrong, it is strongly recommended that you take LibreTime off-air until the problem is fixed.
If the time on your server is wrong, we strongly recommend that you take LibreTime off-air until the problem is fixed.
### Configuring NTP
## Configuring NTP
Although it is possible to set the date and time of the server manually, this is not recommended because the server clock can drift over time, compromising the accuracy of your broadcast schedule. If your LibreTime server is permanently connected to the Internet, you can synchronize your server to a time server with the **ntp** program. If **ntp** is not yet installed, you can enter the following command on Debian or Ubuntu:
sudo apt-get install ntp
Although it is possible to set the date and time of the server manually, this is not recommended because the server clock can drift over time, compromising the accuracy of your broadcast schedule. If your LibreTime server is permanently connected to the Internet, you can synchronize your server to a time server with the **ntp** program. If **ntp** is not on your server, you can install it with `sudo apt-get install ntp`.
Optionally, open the **ntp** configuration file in the **nano** editor to add further time server names:
@ -23,51 +22,49 @@ Optionally, open the **ntp** configuration file in the **nano** editor to add fu
On Ubuntu GNU/Linux, the default time server is _ntp.ubuntu.com_, but there are many other time servers available on the public Internet, including the group of servers listed at <http://www.pool.ntp.org/> for each country. Using a variety of NTP servers located closely to your LibreTime server should produce the most accurate results. For example, for a server in the United Kingdom you could use the following list:
# You do need to talk to an NTP server or two (or three).
server ntp.ubuntu.com
server 0.uk.pool.ntp.org
server 1.uk.pool.ntp.org
server 2.uk.pool.ntp.org
server 3.uk.pool.ntp.org
```title="/etc/ntp.conf"
# You do need to talk to an NTP server or two (or three).
server ntp.ubuntu.com
server 0.uk.pool.ntp.org
server 1.uk.pool.ntp.org
server 2.uk.pool.ntp.org
server 3.uk.pool.ntp.org
```
Enter the server names you require, press **Ctrl+O** to write out the _/etc/ntp.conf_ file, then **Ctrl+X** to exit **nano**. Restart the **ntp** service with:
sudo invoke-rc.d ntp restart
Enter the server names you require, press **Ctrl+O** to write out the _/etc/ntp.conf_ file, then **Ctrl+X** to exit **nano**. Restart the **ntp** service with `sudo systemctl restart ntp`.
The server should respond:
* Stopping NTP server ntpd [ OK ]
* Starting NTP server ntpd [ OK ]
```
* Stopping NTP server ntpd [ OK ]
* Starting NTP server ntpd [ OK ]
```
Then use the **ntpq -p** command to confirm that **ntp** is working. This command should produce output similar to the following:
ntpq -p
remote refid st t when poll reach delay offset jitter
==================================================================
europium. 193.79.237.14 2 u 28 64 3 39.571 12.600 3.590
norb.v4.c 46.227.200.72 3 u 28 64 3 47.856 -6.908 10.028
82.113.15 193.62.22.82 2 u 29 64 3 11.458 -0.513 2.629
ntppub.le 158.43.192.66 2 u 91 64 2 122.781 44.864 0.001
dns0.rmpl 195.66.241.3 2 u 27 64 3 22.171 1.464 4.242
```
ntpq -p
remote refid st t when poll reach delay offset jitter
==================================================================
europium. 193.79.237.14 2 u 28 64 3 39.571 12.600 3.590
norb.v4.c 46.227.200.72 3 u 28 64 3 47.856 -6.908 10.028
82.113.15 193.62.22.82 2 u 29 64 3 11.458 -0.513 2.629
ntppub.le 158.43.192.66 2 u 91 64 2 122.781 44.864 0.001
dns0.rmpl 195.66.241.3 2 u 27 64 3 22.171 1.464 4.242
```
### Adjusting the server time zone
## Adjusting the server time zone
The data centre which hosts your LibreTime server could be located anywhere in the world. Some servers are set to _Coordinated Universal Time_ or UTC (similar to _Greenwich Mean Time_ or GMT), regardless of their location. LibreTime uses UTC time in its database for scheduling purposes, independent of the server time zone.
If the server time zone is not appropriate for integration with your station's other systems, on a Debian or Ubuntu server you can reconfigure the **tzdata** (time zone data) package with the command:
Find your timezone's shortcode with `timedatectl list-timezones`, then enter
sudo dpkg-reconfigure tzdata
```bash
sudo timedatectl set-timezone your_time_zone
```
This command opens a menu in which you can select the continent that you require, by pressing the Enter key.
:::tip
![](/img/Screenshot15-Configuring_tzdata.png)
You can check to see which time zone your server is set to by running `timedatectl` without any arguments.
The next step is to select your nearest city, again by pressing the Enter key. The appropriate time zone is selected according to the information that you have entered.
![](/img/Screenshot16-Configure_city.png)
The console output from the **dpkg-reconfigure tzdata** command will confirm the new setting:
Current default time zone: 'Europe/London'
Local time is now: Tue Jul 2 15:18:01 BST 2013.
Universal Time is now: Tue Jul 2 14:18:01 UTC 2013.
:::

132
docs/getting-started/ssl.md
View file

@ -1,54 +1,22 @@
---
title: SSL Configuration
layout: article
category: install
sidebar_position: 4
---
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
## Deploying a certificate with Certbot (Recommended)
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. There are some requirements for this process:
Electronic Frontier Foundation. To use Certbot, your Libretime installation must be open to the internet on port 80.
- you have an HTTP website (already installed and configured by default by the LibreTime installer) and
- this website is open to the public internet (likely via. port forwarding if your computer is behind a firewall) and
- the server is accessible to the public via. 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.
If you aren't able to verify all three requirements, you may want to try a self-signed certificate (see next section).
If you aren't able to use Certbot, you may want to try a self-signed certificate.
These instructions come from Certbot's website and assume that you are using an Apache web server
running on Ubuntu 18.04 LTS (the Apache web server is installed with LibreTime by default).
Instructions for other Debian-based OSes are similar, but check with Certbot for clarification.
## Deploying a self-signed certificate
Note: all instructions require you to have sudo privileges
First, add Certbot's PPA using:
```
sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository universe
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
```
Next, install Certbot and install the SSL certificate using the below commands:
```
sudo apt-get install certbot python3-certbot-apache
sudo certbot --apache # get and install the certificate
sudo certbot certonly --apache # to only get the certificate, not install it using Certbot
```
You can test certificate renewal by running `sudo certbot renew --dry-run`.
Head to your server's IP address to check to see that the installation worked.
### Deploying a self-signed certificate
The Debian/Ubuntu package _ssl-cert_ creates a _snakeoil_ certificate and key based on your server's hostname. This gratis certificate and key pair created under the _/etc/ssl/certs_/ and _/etc/ssl/private/_ directories will not be recognised by users' browsers without manual intervention. You can install the _ssl-cert_ package with the command:
sudo apt-get install ssl-cert
The Debian/Ubuntu package _ssl-cert_ creates a _snakeoil_ certificate and key based on your server's hostname. This gratis certificate and key pair created under the _/etc/ssl/certs_/ and _/etc/ssl/private/_ directories will not be recognised by users' browsers without manual intervention. You can install the _ssl-cert_ package with `sudo apt-get install ssl-cert`.
If the hostname of your server does not match the domain name you intend to use with the LibreTime virtual host, the user's browser will present an additional security warning. You can set the domain name of the certificate by editing the file _/usr/share/ssl-cert/ssleay.cnf_ to replace the _@HostName@_ variable:
@ -58,84 +26,88 @@ with the domain name used by LibreTime:
commonName = airtime.example.com
Then save the file and regenerate the certificate with the command:
Then save the file and regenerate the certificate with
sudo make-ssl-cert generate-default-snakeoil --force-overwrite
```bash
sudo make-ssl-cert generate-default-snakeoil --force-overwrite
```
You should enable additional Apache modules for page redirections, custom headers and secure access:
sudo a2enmod alias headers ssl
```bash
sudo a2enmod alias headers ssl
```
Next, edit the virtual host configuration for your LibreTime server to include a stanza for the https:// interface on port 443 and a redirect for logins from port 80:
sudo nano /etc/apache2/sites-available/airtime-vhost.conf
```bash
sudo nano /etc/apache2/sites-available/airtime-vhost.conf
```
Using the following configuration for Apache 2.2 as a guide, replace _airtime.example.com_ with the name of your server and *admin@example.com* with your email address. The older SSLv2 and SSLv3 protocols and SSL compression should be disabled, as they are generally believed to be insecure. You may wish to create a _ServerAlias_ for users to access the administration interface over https:// if required.
Using the following configuration as a guide, replace _libretime.example.com_ with the name of your server and *admin@example.com* with your email address. The older SSLv2 and SSLv3 protocols and SSL compression should be disabled, as they are generally believed to be insecure. You may wish to create a _ServerAlias_ for users to access the administration interface over https:// if required.
On port 80, Apache's _alias_ module is used to set a _Redirect permanent_ for the login page. Optionally, access could be denied to all sites except _localhost_ and any other LibreTime servers on your network, so that unencrypted communication between LibreTime components can continue.
```
```apacheconf title="/etc/apache2/sites-available/airtime-vhost.conf"
<VirtualHost *:443>
SSLEngine on
SSLProtocol All -SSLv2 -SSLv3
SSLCompression off
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
Header always set Strict-Transport-Security "max-age=31536000"
SSLEngine on
SSLProtocol All -SSLv2 -SSLv3
SSLCompression off
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
Header always set Strict-Transport-Security "max-age=31536000"
ServerName airtime.example.com
#ServerAlias www.example.com
ServerName libretime.example.com
#ServerAlias www.example.com
ServerAdmin admin@example.com
ServerAdmin admin@example.com
DocumentRoot /usr/share/airtime/php/legacy/public
DirectoryIndex index.php
DocumentRoot /usr/share/airtime/php/legacy/public
DirectoryIndex index.php
<Directory /usr/share/airtime/php/legacy/public>
Options -Indexes FollowSymLinks MultiViews
AllowOverride all
Order allow,deny
Allow from all
</Directory>
<Directory /usr/share/airtime/php/legacy/public>
Options -Indexes FollowSymLinks MultiViews
AllowOverride all
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
<VirtualHost *:80>
ServerName airtime.example.com
ServerName libretime.example.com
ServerAdmin admin@example.com
ServerAdmin admin@example.com
DocumentRoot /usr/share/airtime/php/legacy/public
Redirect permanent /login https://airtime.example.com/login
DocumentRoot /usr/share/airtime/php/legacy/public
Redirect permanent /login https://airtime.example.com/login
SetEnv APPLICATION_ENV "production"
SetEnv APPLICATION_ENV "production"
<Directory /usr/share/airtime/php/legacy/public>
Options -Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
Allow from all
</Directory>
<Directory /usr/share/airtime/php/legacy/public>
Options -Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
```
Save the file with **Ctrl+O** and exit the **nano** editor with **Ctrl+X**. Then restart Apache with the command:
Save the file, then restart Apache with `sudo systemctl restart apache2`.
sudo service apache restart
When attempting to log into your server via http:// in future, you should be redirected to https:// automatically.
When attempting to log into your server via `http://` in future, you should be redirected to `https://` automatically.
### Importing a self-signed certificate into the browser
The first time you access an LibreTime server with a self-signed certificate over https:// your browser will block the login page and display a security warning. In **Mozilla Firefox**, you can click **Technical Details** to confirm that the warning is due to the certificate being self-signed before clicking the **Add Exception** button. In **Google Chrome**, the button to click on the security warning page is **Proceed Anyway**.
![](/img/Screenshot547-connection_untrusted.png)
![](./ssl-screenshot547-connection_untrusted.png)
On the next page in Firefox, click the **Get Certificate** button to inspect the details of the self-signed certificate. If all is well, click the **Confirm Security Exception** button. You should now be able to proceed to the https:// login page.
![](/img/Screenshot548-confirm_exception.png)
![](./ssl-screenshot548-confirm_exception.png)
If the users of your LibreTime server wish to avoid going through these steps, or they do not trust the remote LibreTime server to be what it claims to be, it is also possible to import a trusted local copy of a certificate file into the browser. For example, in Firefox version 30 preferences, you can go into the **Advanced** section, click the **Certificates** tab, then click the **View Certificates** button. On the **Servers** tab of the **Certificate Manager**, there is an **Import** button which enables you to load a certificate file from the local computer.
### Mixed encrypted and unencrypted content
## 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.