[docs] unify nginx explainers and add apache httpd (#455)

* docs: unify nginx explainers and add apache httpd there are two places where nginx + certbot is explained, unify that into one place. Add apache httpd, following the same steps, but using mod_md for LetsEncrypt add a note about #453 in both guides. Link to both, and call the section reverse proxy, instead of NGINX * restore full nginx.conf from docker.md * add installation_guide/apache-httpd.md to mkdocs
2024-11-23 00:33:50 +01:00 · 2022-04-18 17:45:43 +02:00 · 2022-04-18 17:45:43 +02:00 · 721061b046
commit 721061b046
parent 1e3b38573d
5 changed files with 202 additions and 66 deletions
--- a/docs/installation_guide/apache-httpd.md
+++ b/docs/installation_guide/apache-httpd.md
@ -0,0 +1,129 @@
+# Reverse proxy with Apache httpd
+
+## Requirements
+
+For this you will need Apache httpd server.
+That is a fairly popular package so your distro will probably have it.
+
+### Ubuntu
+
+```bash
+sudo apt install apache2
+```
+
+### Arch
+
+```bash
+sudo pacman -S apache
+```
+
+### OpenSuse
+
+```bash
+sudo zypper install apache2
+```
+
+## Configure GoToSocial
+
+In your GoToSocial config turn off letsencrypt.
+First open the file in your text editor.
+
+```bash
+sudoedit /gotosocial/config.yaml
+```
+
+Then set `letsencrypt-enabled: false`.
+
+If GoToSocial is already running, restart it.
+
+```bash
+sudo systemctl restart gotosocial.service
+```
+
+Or if you don't have a systemd service just restart it manually.
+
+## Set up Apache httpd
+
+First we will set up Apache httpd to serve GoToSocial as unsecured http and then later use certbot to automatically upgrade to https.
+Please do not try to use it until that's done or you'll be transmitting passwords over clear text.
+
+First we'll write a configuration for Apache httpd and put it in `/etc/apache2/sites-available`.
+
+```bash
+sudo mkdir /etc/apache2/sites-available/
+sudoedit /etc/apache2/sites-available/yourgotosocial.url.conf
+```
+
+The file you're about to create should look a bit like this:
+
+```apache
+<VirtualHost *:80>
+  ServerName example.com
+  ProxyPreserveHost On
+  ProxyPass / http://localhost:8080/
+  ProxyPassReverse / http://localhost:8080/
+</VirtualHost>
+```
+
+**Note***: `ProxyPreserveHost On` is essential: It guarantees that the proxy and the gotosocial speak of the same Server name. If not, gotosocial will build the wrong authentication headers, and all attempts at federation will be rejected with 401.
+
+Change `ProxyPass` to the ip and port that you're actually serving GoToSocial on and change `ServerName` to your own domain name.
+If your domain name is `gotosocial.example.com` then `ServerName gotosocial.example.com;` would be the correct value.
+If you're running GoToSocial on another machine with the local ip of 192.168.178.69 and on port 8080 then `ProxyPass / http://192.168.178.69:8080/` would be the correct value.
+
+Next we'll need to link the file we just created to the folder that Apache httpd reads configurations for active sites from.
+
+```bash
+sudo mkdir /etc/apache2/sites-enabled
+sudo ln -s /etc/apache2/sites-available/yourgotosocial.url.conf /etc/apache2/sites-enabled/
+```
+
+Now check for configuration errors.
+
+```bash
+sudo apachectl -t
+```
+
+If everything is fine you should get this as output:
+
+```text
+Syntax OK
+```
+
+Everything working? Great! Then restart Apache httpd to load your new config file.
+
+```bash
+sudo systemctl restart apache2
+```
+
+## Setting up SSL with mod_md
+
+To setup Apache httpd with mod_md, we'll need to load the module and then modify our vhost files:
+
+```apache
+MDomain example auto
+
+<VirtualHost *:80>
+  ServerName example.com
+</VirtualHost>
+
+<VirtualHost *:443>
+  SSLEngine On
+  ServerName example.com
+  ProxyPreserveHost On
+  ProxyPass / http://localhost:8080/
+  ProxyPassReverse / http://localhost:8080/
+  RequestHeader set "X-Forwarded-Proto" expr=https
+</VirtualHost>
+```
+
+This allows mod_md to take care of the SSL setup, and it will also redirect from http to https.
+After we put ths into place, we'll need  to restart Apache httpd
+
+```bash
+sudo systemctl restart apache2
+```
+
+and monitor the logs to see when the new certificate arrives, and then reload it one last time and after that you should be good to go!
+
+Apache httpd needs to be restart (or reloaded), every time mod_md gets a new certificate, see the module's docs for [more information](https://github.com/icing/mod_md#how-to-manage-server-reloads) on that.
--- a/docs/installation_guide/binary.md
+++ b/docs/installation_guide/binary.md
@ -138,6 +138,6 @@ sudo systemctl enable --now gotosocial.service

 At some point you'll likely want to do things like change instance information, and block domains you don't want to interact with. See the [admin panel](../admin/admin_panel.md) instructions for this.

-## 9. Reverse proxy with nginx (optional)
+## 9. Reverse proxy (optional)

-If you want to run other webservers on port 433 or simply want to add an additional layer of security you might want to [use nginx as a reverse proxy](./nginx.md).
+If you want to run other webservers on port 433 or want to add an additional layer of security you might want to use [nginx](./nginx.md) or [Apache httpd](./apache-httpd.md) as reverse proxy
--- a/docs/installation_guide/docker.md
+++ b/docs/installation_guide/docker.md
@ -125,66 +125,6 @@ GTS_LETSENCRYPT_ENABLED=false
 ```
 </details>

-## (optional) NGINX Config
-The following NGINX config is just an example of what this might look like. In this case we assume that a valid SSL certificate is present. For this you can get a valid certificate from [Let's Encrypt](https://letsencrypt.org "Let's Encrypt Homepage") with the [cerbot](https://certbot.eff.org "Certbot's Homepage").
+## (optional) Reverse Proxy

-```shell
-server {
-  listen 80;
-  listen [::]:80;
-  server_name gts.example.com;
-
-  location /.well-known/acme-challenge/ {
-    default_type "text/plain";
-    root /var/www/certbot;
-  }
-  location / { return 301 https://$host$request_uri; }
-}
-
-server {
-  listen 443 ssl http2;
-  listen [::]:443 ssl http2;
-  server_name gts.example.com;
-
-  #############################################################################
-  # Certificates                                                              #
-  # you need a certificate to run in production. see https://letsencrypt.org/ #
-  #############################################################################
-  ssl_certificate     /etc/letsencrypt/live/gts.example.com/fullchain.pem;
-  ssl_certificate_key /etc/letsencrypt/live/gts.example.com/privkey.pem;
-
-  location ^~ '/.well-known/acme-challenge' {
-    default_type "text/plain";
-    root /var/www/certbot;
-  }
-
-  ###########################################
-  # Security hardening (as of Nov 15, 2020) #
-  # based on Mozilla Guideline v5.6         #
-  ###########################################
-
-  ssl_protocols             TLSv1.2 TLSv1.3;
-  ssl_prefer_server_ciphers on;
-  ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305";
-  ssl_session_timeout       1d; # defaults to 5m
-  ssl_session_cache         shared:SSL:10m; # estimated to 40k sessions
-  ssl_session_tickets       off;
-  ssl_stapling              on;
-  ssl_stapling_verify       on;
-  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
-  # HSTS (https://hstspreload.org), requires to be copied in 'location' sections that have add_header directives
-  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload";
-
-
-  location / {
-    proxy_pass         http://127.0.0.1:8080;
-
-    proxy_set_header   Host             $host;
-    proxy_set_header   Connection       $http_connection;
-    proxy_set_header   X-Real-IP        $remote_addr;
-    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
-    proxy_set_header   X-Scheme         $scheme;
-  }
-
-}
-```
+If you want to run other webservers on port 433 or want to add an additional layer of security you might want to use [nginx](./nginx.md) or [Apache httpd](./apache-httpd.md) as reverse proxy
--- a/docs/installation_guide/nginx.md
+++ b/docs/installation_guide/nginx.md
@ -68,7 +68,9 @@ server {
 }
 ```

-Note: You can remove the line `listen [::]:80;` if your server is not ipv6 capable or you'd rather not use ipv6.
+**Note***: You can remove the line `listen [::]:80;` if your server is not ipv6 capable.
+
+**Note***: `proxy_set_header Host $host;` is essential: It guarantees that the proxy and the gotosocial speak of the same Server name. If not, gotosocial will build the wrong authentication headers, and all attempts at federation will be rejected with 401.

 Change `proxy_pass` to the ip and port that you're actually serving GoToSocial on and change `server_name` to your own domain name.
 If your domain name is `gotosocial.example.com` then `server_name gotosocial.example.com;` would be the correct value.
@ -109,8 +111,72 @@ sudo certbot --nginx
 ```

 After you do, it should have automatically edited your configuration file to enable https.
-Just reload it one last time and after that you should be good to go!
+Reload it one last time and after that you should be good to go!

 ```bash
 sudo systemctl restart nginx
 ```
+
+### Results
+
+The resulting NGINX config should look something like this:
+
+```nginx.conf
+server {
+  listen 80;
+  listen [::]:80;
+  server_name gts.example.com;
+
+  location /.well-known/acme-challenge/ {
+    default_type "text/plain";
+    root /var/www/certbot;
+  }
+  location / { return 301 https://$host$request_uri; }
+}
+
+server {
+  listen 443 ssl http2;
+  listen [::]:443 ssl http2;
+  server_name gts.example.com;
+
+  #############################################################################
+  # Certificates                                                              #
+  # you need a certificate to run in production. see https://letsencrypt.org/ #
+  #############################################################################
+  ssl_certificate     /etc/letsencrypt/live/gts.example.com/fullchain.pem;
+  ssl_certificate_key /etc/letsencrypt/live/gts.example.com/privkey.pem;
+
+  location ^~ '/.well-known/acme-challenge' {
+    default_type "text/plain";
+    root /var/www/certbot;
+  }
+
+  ###########################################
+  # Security hardening (as of Nov 15, 2020) #
+  # based on Mozilla Guideline v5.6         #
+  ###########################################
+
+  ssl_protocols             TLSv1.2 TLSv1.3;
+  ssl_prefer_server_ciphers on;
+  ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305";
+  ssl_session_timeout       1d; # defaults to 5m
+  ssl_session_cache         shared:SSL:10m; # estimated to 40k sessions
+  ssl_session_tickets       off;
+  ssl_stapling              on;
+  ssl_stapling_verify       on;
+  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+  # HSTS (https://hstspreload.org), requires to be copied in 'location' sections that have add_header directives
+  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload";
+
+
+  location / {
+    proxy_pass         http://127.0.0.1:8080;
+
+    proxy_set_header   Host             $host;
+    proxy_set_header   Connection       $http_connection;
+    proxy_set_header   X-Real-IP        $remote_addr;
+    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
+    proxy_set_header   X-Scheme         $scheme;
+  }
+}
+```
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -18,6 +18,7 @@ nav:
    - "installation_guide/binary.md"
    - "installation_guide/docker.md"
    - "installation_guide/nginx.md"
+    - "installation_guide/apache-httpd.md"
    - "installation_guide/third_party.md"
  - "Configuration":
    - "configuration/index.md"