Merge branch 'main' into issue474-fix-upnp-not-playable

docs/README.md

@@ -7,6 +7,9 @@
 
 - [Configures](./configures/README.md)
   - [Detail Configuration](./configures/detail.md)
+- Proxy
+  - [Prerequisites](./proxy/README.md)
+  - [Apache](./proxy/apache.md)
 - Media
   - [Jukebox](./media/jukebox.md)
 - [TroubleShooting](./troubleshooting.md)

docs/proxy/README.md

@@ -0,0 +1,78 @@
+# Setting up a reverse proxy
+
+A reverse proxy is a public-facing web server sitting in front of an internal server such as Airsonic Advanced. The Airsonic Advanced server never communicates with the outside ; instead, the reverse proxy handles all HTTP(S) requests and forwards them to Airsonic Advanced.
+
+This is useful in many ways, such as gathering all web configuration in the same place. It also handles some options (HTTPS) much better than the bundled Airsonic Advanced server or a servlet container such as Tomcat.
+
+This guide assumes you already have a working Airsonic Advanced installation after following the [installation guide](https://airsonic.github.io/docs/install/prerequisites/).
+
+## Getting a TLS certificate
+This guide assumes you already have a TLS certificate. [Let’s Encrypt](https://letsencrypt.org/getting-started/) currently provides such certificates for free using the [certbot software](https://certbot.eff.org/).
+
+## Configure Airsonic Advanced
+
+### Basic configuration
+
+A few settings should be tweaked via Spring Boot or Tomcat configuration:
+
+- Set the context path if needed (the rest of this guide assumes `/airsonic`, the default value is `/`)
+- Set the correct address to listen to (the rest of this guide assumes `127.0.0.1`)
+- Set the correct port to listen to (the rest of this guide assumes `4040`)
+  - If you see `airsonic.github.io`, its guide assumes `8080` as the default port
+
+To change this, please use one of the guide below according to your installation:
+
+- [Tomcat](https://airsonic.github.io/docs/configure/tomcat/)
+- [Standalone](https://airsonic.github.io/docs/configure/standalone/)
+
+### Forward headers
+
+You will also need to make sure Airsonic Advanced uses the correct headers for redirects, by setting the `server.forward-headers-strategy` property to `native` or `framework`.
+
+To do so, stop your Airsonic Advanced server or Docker image, then edit the config/application.properties file:
+
+```
+nano /path/to/airsonic/config/application.properties
+```
+
+Add the following line to the bottom of the file:
+
+```
+server.forward-headers-strategy=native
+```
+
+or 
+
+```
+server.forward-headers-strategy=framework
+```
+
+Use Ctrl+X to save and exit the file, and restart your Airsonic server or Docker image.
+
+## Reverse proxy configuration
+
+### How it works
+
+Airsonic expects proxies to provide information about their incoming URL so that Airsonic can craft it when needed. To do so, Airsonic looks for the following HTTP headers:
+
+- `X-Forwarded-Host`
+    - Provides server name and optionally port in the case that the proxy is on a non-standard port
+- `X-Forwarded-Proto`
+    - Tells Airsonic whether to craft an HTTP or HTTPS url
+- `X-Forwarded-Server`
+    - This is only a fallback in the case that `X-Forwarded-Host` is not available
+
+Currently this is used wherever, `NetworkUtil#getBaseUrl` is called. A couple notable places include:
+
+- Stream urls
+- Share urls
+- Coverart urls
+
+## Provided configurations
+
+Use a guide in the list below:
+
+- [Configure Apache proxy](./apache.md)
+- [Configure Nginx proxy](https://airsonic.github.io/docs/proxy/nginx/)
+- [Configure Haproxy proxy](https://airsonic.github.io/docs/proxy/haproxy)
+- [Configure Caddy proxy](https://airsonic.github.io/docs/proxy/caddy)

docs/proxy/apache.md

@@ -0,0 +1,93 @@
+# Setting up Apache
+
+The following configurations works for HTTPS (with an HTTP redirection).
+
+> NOTE: Make sure you follow the [prerequisites](./README.md).
+
+### Airsonic Advanced configuration
+
+You will need to make sure Airsonic Advanced uses the correct headers for redirects, by setting the `server.forward-headers-strategy` property to `native` or `framework`.
+
+`framework` is the recommended value, but you can set it to `native` if you want to use the Apache headers.
+
+### Apache configuration
+
+Create a new virtual host file:
+
+```
+sudo nano /etc/apache2/sites-available/airsonic.conf
+```
+
+Paste the following configuration in the virtual host file:
+
+```
+<VirtualHost *:80>
+    ServerName example.com
+    Redirect permanent / https://example.com/
+</VirtualHost>
+
+<VirtualHost *:443>
+    ServerName example.com
+
+    SSLEngine On
+    SSLCertificateFile cert.pem
+    SSLCertificateKeyFile key.pem
+    SSLProxyEngine on
+
+    LogLevel warn
+    
+    ProxyPass         /airsonic/websocket ws://127.0.0.1:4040/airsonic/websocket
+    ProxyPassReverse  /airsonic/websocket ws://127.0.0.1:4040/airsonic/websocket
+    ProxyPass         /airsonic http://127.0.0.1:4040/airsonic
+    ProxyPassReverse  /airsonic http://127.0.0.1:4040/airsonic
+    RequestHeader     set       X-Forwarded-Proto "https"
+</VirtualHost>
+```
+
+Alternatively, if you want to use an existing configuration, you can also paste the configuration below inside an existing `VirtualHost` block:
+
+```
+ProxyPass         /airsonic/websocket ws://127.0.0.1:4040/airsonic/websocket
+ProxyPassReverse  /airsonic/websocket ws://127.0.0.1:4040/airsonic/websocket
+ProxyPass         /airsonic http://127.0.0.1:8080/airsonic
+ProxyPassReverse  /airsonic http://127.0.0.1:8080/airsonic
+RequestHeader     set       X-Forwarded-Proto "https"
+```
+You will need to make a couple of changes in the configuration file:
+
+- Replace `example.com` with your own domain name.
+- Be sure to set the right path to your `cert.pem` and `key.pem` files.
+- Change `/airsonic` following your Airsonic context path.
+- Change `http://127.0.0.1:4040/airsonic` following you Airsonic Advanced server location, port and path.
+
+Activate the host:
+
+```
+sudo a2ensite airsonic.conf
+```
+
+Activate the following Apache modules:
+
+```
+sudo a2enmod proxy
+sudo a2enmod proxy_http
+sudo a2enmod proxy_wstunnel
+sudo a2enmod ssl
+sudo a2enmod headers
+```
+
+Restart the `apache2` service:
+
+```
+sudo systemctl restart apache2.service
+```
+
+## Content Security Policy
+
+You may face some `Content-Security-Policy` issues. To fix this, add the following line to your Apache configuration:
+
+```
+<Location /airsonic>
+    Header set Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' www.gstatic.com; img-src 'self' *.akamaized.net; style-src 'self' 'unsafe-inline' fonts.googleapis.com; font-src 'self' fonts.gstatic.com; frame-src 'self'; object-src 'none'"
+</Location>
+```