diff --git a/docs/manual/getting-started/index.md b/docs/manual/getting-started/index.md index fae538bb5..544b6c57c 100644 --- a/docs/manual/getting-started/index.md +++ b/docs/manual/getting-started/index.md @@ -86,15 +86,3 @@ your LibreTime server has made to this Icecast server. If you have only just installed LibreTime, there may not be any media playing out yet. ![](static/Screenshot293-Icecast_status_page.png) - -Reverse Proxy Connections -------------------------- -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 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**](/manual/general/). These origins should include any -domains that will be used externally to connect to your reverse proxy that you -want handled by LibreTime. diff --git a/docs/manual/reverse-proxy/index.md b/docs/manual/reverse-proxy/index.md new file mode 100644 index 000000000..a10a8c0dc --- /dev/null +++ b/docs/manual/reverse-proxy/index.md @@ -0,0 +1,117 @@ +# Reverse Proxy Connections + +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 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**](/manual/general/). 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 + +## Reverse Proxy Basics + +A reverse proxy allows the LibreTime server to not be connected to the open internet. In +this configuration, it is 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 is not. All the SSL certificates +live on the reverse proxy and can be renewed there instead of on the individual +containers. + +## Setup + +There are known bugs when using LibreTime behind a reverse proxy ([#957](https://github.com/LibreTime/libretime/issues/957) +tracks the issue and contains a temporary workaround). 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 will also 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 `proxy` and LibreTime will be installed on `libretime`. You will need root +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 `localhost` in +`/etc/icecast2/icecast.xml` with the following: + +``` +icecast.example.com +``` + +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 +``` + +On `proxy`, run the following: + +``` +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://libretime/; + } +} +EOF +``` + +This Nginx configuration ensures that all traffic uses SSL to the reverse proxy, and +traffic is proxied to `libretime`. + +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](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 +``` diff --git a/mkdocs.yml b/mkdocs.yml index 070832ac9..9d07b5cb4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,7 @@ pages: - 'Preparing the Server': manual/preparing-the-server/index.md - 'Setting the Server Time': manual/setting-the-server-time/index.md - 'Host Configuration': manual/host-configuration/index.md + - 'Reverse Proxy': manual/reverse-proxy/index.md - 'Using LibreTime': - 'On Air in 60 seconds!': 'manual/on-air-in-60-seconds/index.md' - 'Getting Started': manual/getting-started/index.md