[docs] Revamp the installation guide (#1877)

This tries to revamp/restructure the installation guide. It's renamed to
"Getting Started" as it now contains a few more things than just the
installation, especially the deployment considerations which we didn't
use to spell out as much ahead of time.

Installation is now a section with the guides on their own. I've removed
a bit of redundancy like the user creation. I also removed the rogue
reverse proxy section in the Docker guide and lifted that into the
reverse proxy section.

5 files changed, 630 insertions, 0 deletions

diff --git a/docs/getting_started/reverse_proxy/apache-httpd.md b/docs/getting_started/reverse_proxy/apache-httpd.md
new file mode 100644
index 000000000..9522a0001
--- /dev/null
+++ b/docs/getting_started/reverse_proxy/apache-httpd.md
@@ -0,0 +1,250 @@
+# Apache HTTP Server
+
+## Requirements
+
+For this you will need the Apache HTTP 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
+```
+
+### Install modules
+
+You'll also need to install additional modules for Apache HTTP Server. You can do that with the following command:
+
+```bash
+sudo a2enmod proxy_http md ssl headers rewrite
+```
+
+## Configure GoToSocial
+
+We're going to have Apache handle LetsEncrypt certificates, so you need to turn off built-in LetsEncrypt support in your GoToSocial config.
+
+First open the file in your text editor:
+
+```bash
+sudoedit /gotosocial/config.yaml
+```
+
+Then set `letsencrypt-enabled: false`.
+
+If the reverse proxy will be running on the same machine, set the `bind-address` to `"localhost"` so that the GoToSocial server is only accessible via loopback. Otherwise it may be possible to bypass your proxy by connecting to GoToSocial directly, which might be undesirable.
+
+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 HTTP Server with SSL managed using MD module
+
+Now we'll configure Apache HTTP Server to serve GoToSocial requests.
+
+First we'll write a configuration for Apache HTTP Server and put it in `/etc/apache2/sites-available`:
+
+```bash
+sudo mkdir -p /etc/apache2/sites-available/
+sudoedit /etc/apache2/sites-available/example.com.conf
+```
+
+In the above `sudoedit` command, replace `example.com` with the hostname of your GoToSocial server.
+
+The file you're about to create should look a bit like this:
+
+```apache
+MDomain example.com auto
+MDCertificateAgreement accepted
+
+<VirtualHost *:80 >
+  ServerName example.com
+</VirtualHost>
+
+<VirtualHost *:443>
+  ServerName example.com
+
+  RewriteEngine On
+  RewriteCond %{HTTP:Upgrade} websocket [NC]
+  RewriteCond %{HTTP:Connection} upgrade [NC]
+  # set to 127.0.0.1 instead of localhost to work around https://stackoverflow.com/a/52550758
+  RewriteRule ^/?(.*) "ws://127.0.0.1:8080/$1" [P,L]
+
+  SSLEngine On
+  ProxyPreserveHost On
+  # set to 127.0.0.1 instead of localhost to work around https://stackoverflow.com/a/52550758
+  ProxyPass / http://127.0.0.1:8080/
+  ProxyPassReverse / http://127.0.0.1:8080/
+
+  RequestHeader set "X-Forwarded-Proto" expr=https
+</VirtualHost>
+```
+
+or, if you have [Apache httpd 2.4.47+](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#protoupgrade), you can get rid of both `mod_rewrite` and `mod_proxy_wstunnel` and simplify the whole config to:
+
+```apache
+MDomain example.com auto
+MDCertificateAgreement accepted
+
+<VirtualHost *:80 >
+  ServerName example.com
+</VirtualHost>
+
+<VirtualHost *:443>
+  ServerName example.com
+
+  SSLEngine On
+  ProxyPreserveHost On
+  # set to 127.0.0.1 instead of localhost to work around https://stackoverflow.com/a/52550758
+  ProxyPass / http://127.0.0.1:8080/ upgrade=websocket
+  ProxyPassReverse / http://127.0.0.1:8080/
+
+  RequestHeader set "X-Forwarded-Proto" expr=https
+</VirtualHost>
+```
+
+Again, replace occurrences of `example.com` in the above config file with the hostname of your GtS server. If your domain name is `gotosocial.example.com`, then `gotosocial.example.com` would be the correct value.
+
+You should also change `http://127.0.0.1:8080` to the correct address and port (if it's not on `127.0.0.1:8080`) of your GtS server. For example, if you're running GoToSocial on another machine with the local ip of `192.168.178.69` and on port `8080` then `http://192.168.178.69:8080/` would be the correct value.
+
+`Rewrite*` directives are needed to ensure that Websocket streaming connections also work. See the [websocket](./websocket.md) document for more information on this.
+
+`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 Unauthorized.
+
+By default, apache sets `X-Forwarded-For` in forwarded requests. To make this and rate limiting work, set the `trusted-proxies` configuration variable. See the [rate limiting](../../api/ratelimiting.md) and [general configuration](../../configuration/general.md) docs
+
+Save and close the config file.
+
+Now we'll need to link the file we just created to the folder that Apache HTTP Server reads configurations for active sites from.
+
+```bash
+sudo mkdir /etc/apache2/sites-enabled
+sudo ln -s /etc/apache2/sites-available/example.com.conf /etc/apache2/sites-enabled/
+```
+
+In the above `ln` command, replace `example.com` with the hostname of your GoToSocial server.
+
+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 HTTP Server to load your new config file.
+
+```bash
+sudo systemctl restart apache2
+```
+
+Now, monitor the logs to see when the new LetsEncrypt certificate arrives (`tail -F /var/log/apache2/error.log`), and then reload Apache one last time with the above `systemctl restart` command. After that you should be good to go!
+
+Apache HTTP Server 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).
+
+Depending on your version of Apache HTTP Server, you may see the following error: `error (specific information not available): acme problem urn:ietf:params:acme:error:invalidEmail: Error creating new account :: contact email "webmaster@localhost" has invalid domain : Domain name needs at least one dot`
+
+If this happens, you'll need to do one (or all) of the below:
+
+1. Update `/etc/apache2/sites-enabled/000-default.conf` and change the `ServerAdmin` value to a valid email address (then reload Apache HTTP Server).
+2. Add the line `MDContactEmail your.email.address@whatever.com` below the `MDomain` line in `/etc/apache2/sites-available/example.com.conf`, replacing `your.email.address@whatever.com` with a valid email address, and `example.com` with your GtS host name.
+
+## Set up Apache HTTP Server with SSL managed manually or by an external software (e.g. Certbot or acme.sh)
+
+If you prefer to have a manual setup or setting SSL using a different service to manage it (Certbot, etc), then you can use a simpler setup for your Apache HTTP Server.
+
+First we'll write a configuration for Apache HTTP Server and put it in `/etc/apache2/sites-available`:
+
+```bash
+sudo mkdir -p /etc/apache2/sites-available/
+sudoedit /etc/apache2/sites-available/example.com.conf
+```
+
+In the above `sudoedit` command, replace `example.com` with the hostname of your GoToSocial server.
+
+The file you're about to create should look initially for both 80 (required) and 443 ports (optional) a bit like this:
+
+```apache
+<VirtualHost *:80>
+  ServerName example.com
+
+  RewriteEngine On
+  RewriteCond %{HTTP:Upgrade} websocket [NC]
+  RewriteCond %{HTTP:Connection} upgrade [NC]
+  # set to 127.0.0.1 instead of localhost to work around https://stackoverflow.com/a/52550758
+  RewriteRule ^/?(.*) "ws://127.0.0.1:8080/$1" [P,L]
+
+  ProxyPreserveHost On
+  # set to 127.0.0.1 instead of localhost to work around https://stackoverflow.com/a/52550758
+  ProxyPass / http://127.0.0.1:8080/
+  ProxyPassReverse / http://127.0.0.1:8080/
+
+</VirtualHost>
+```
+
+Again, replace occurrences of `example.com` in the above config file with the hostname of your GtS server. If your domain name is `gotosocial.example.com`, then `gotosocial.example.com` would be the correct value.
+
+You should also change `http://127.0.0.1:8080` to the correct address and port (if it's not on `127.0.0.1:8080`) of your GtS server. For example, if you're running GoToSocial on another machine with the local ip of `192.168.178.69` and on port `8080` then `http://192.168.178.69:8080/` would be the correct value.
+
+`Rewrite*` directives are needed to ensure that Websocket streaming connections also work. See the [websocket](websocket.md) document for more information on this.
+
+`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 Unauthorized.
+
+In the case of providing an initial setup for the 443 port looking for additional managing by an external tool, you could use default certificates provided by the server which you can find referenced in the `default-ssl.conf` file at `/etc/apache2/sites-available/`.
+
+Save and close the config file.
+
+Now we'll need to link the file we just created to the folder that Apache HTTP Server reads configurations for active sites from.
+
+```bash
+sudo mkdir /etc/apache2/sites-enabled
+sudo ln -s /etc/apache2/sites-available/example.com.conf /etc/apache2/sites-enabled/
+```
+
+In the above `ln` command, replace `example.com` with the hostname of your GoToSocial server.
+
+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 HTTP Server to load your new config file.
+
+```bash
+sudo systemctl restart apache2
+```
+
+## Troubleshooting
+
+If you cannot connect to the site in your browser, the reverse proxy setup doesn't work. Compare the Apache log file (`tail -F /var/log/apache2/access.log`) with the GoToSocial log file. Requests made must show up in both places. Double check the `ProxyPass` setting.
+
+If you can connect but your posts don't federate and your account cannot be found from elsewhere, check your logs. Federation is broken if you see messages attempting to read your profile (something like `level=INFO … method=GET statusCode=401 path=/users/your_username msg="Unauthorized: …"`) or post to your inbox (something like `level=INFO … method=POST statusCode=404 path=/your_username/inbox msg="Not Found: …"`). Double check the `ProxyPreserveHost` setting.
+
+If you can connect but you cannot authorize your account in a Mastodon client app, check your headers. Use `curl -I https://example.com` and look for the `Content-Security-Policy` header. If your webserver sets it, you might have to unset it. One way to do that is to use `Header unset Content-Security-Policy` in the Apache site config file (something like `example.com.conf`).
diff --git a/docs/getting_started/reverse_proxy/caddy.md b/docs/getting_started/reverse_proxy/caddy.md
new file mode 100644
index 000000000..9af8d5e26
--- /dev/null
+++ b/docs/getting_started/reverse_proxy/caddy.md
@@ -0,0 +1,108 @@
+# Caddy 2
+
+## Requirements
+
+For this guide you will need [Caddy 2](https://caddyserver.com/), there are no other dependencies. Caddy manages Lets Encrypt certificates and renewal for them.
+
+Caddy is in the most popular package managers, or you can get a static binary. For all latest installation guides, refer to [their manual](https://caddyserver.com/docs/install).
+
+### Debian, Ubuntu, Raspbian
+
+```bash
+# Add the keyring for their custom repository.
+sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
+
+# Update packages and install it
+sudo apt update
+sudo apt install caddy
+```
+
+### Fedora, Redhat, Centos
+
+```bash
+dnf install 'dnf-command(copr)'
+dnf copr enable @caddy/caddy
+dnf install caddy
+```
+
+### Arch
+
+```bash
+pacman -Syu caddy
+```
+
+### FreeBSD
+```bash
+sudo pkg install caddy
+```
+
+## Configure GoToSocial
+
+If GoToSocial is already running, stop it.
+
+```bash
+sudo systemctl stop gotosocial
+```
+In your GoToSocial config turn off Lets Encrypt by setting `letsencrypt-enabled` to `false`.
+
+If you we running GoToSocial on port 443, change the `port` value back to the default `8080`.
+
+If the reverse proxy will be running on the same machine, set the `bind-address` to `"localhost"` so that the GoToSocial server is only accessible via loopback. Otherwise it may be possible to bypass your proxy by connecting to GoToSocial directly, which might be undesirable.
+
+## Set up Caddy
+
+We will configure Caddy 2 to use GoToSocial on our main domain example.org. Since Caddy takes care of obtaining the Lets Encrypt certificate, we only need to configure it properly once.
+
+In most simple use cases Caddy defaults to a file called Caddyfile. It can reload on changes, or can be configured through an HTTP API for zero downtime, but this is out of our current scope.
+
+```bash
+sudo mkdir -p /etc/caddy
+sudo vim /etc/caddy/Caddyfile
+```
+
+While editing the file above, you should replace 'example.org' with your domain. Your domain should occur twice in the current configuration. If you have chosen another port number for GoToSocial other than port 8080, change the port number on the reverse proxy line to match that.
+
+The file you're about to create should look like this:
+
+```Caddyfile
+example.org {
+	# Optional, but recommended, compress the traffic using proper protocols
+	encode zstd gzip
+
+	# The actual proxy configuration to port 8080 (unless you've chosen another port number)
+	reverse_proxy * http://127.0.0.1:8080 {
+		# Flush immediatly, to prevent buffered response to the client
+		flush_interval -1
+	}
+}
+```
+
+By default, caddy sets `X-Forwarded-For` in forwarded requests. To make this and rate limiting work, set the `trusted-proxies` configuration variable. See the [rate limiting](../../api/ratelimiting.md) and [general configuration](../../configuration/general.md) docs
+
+For advanced configuration check the [reverse_proxy directive](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) at the Caddy documentation.
+
+Now check for configuration errors.
+
+```bash
+sudo caddy validate
+```
+
+If everything is fine, you should get some info lines as output. Unless there are lines marked with *[err]* in front of them, you are all set.
+
+Everything working? Great! Then restart caddy to load your new config file.
+
+```bash
+sudo systemctl restart caddy
+```
+
+If everything went right, you're now all set to enjoy your GoToSocial instance, so we are going to start it again.
+
+```bash
+sudo systemctl start gotosocial
+```
+
+## Results
+
+You should now be able to open the splash page for your instance in your web browser, and will see that it runs under HTTPS!
diff --git a/docs/getting_started/reverse_proxy/index.md b/docs/getting_started/reverse_proxy/index.md
new file mode 100644
index 000000000..927968df0
--- /dev/null
+++ b/docs/getting_started/reverse_proxy/index.md
@@ -0,0 +1,43 @@
+# Reverse proxy
+
+GoToSocial can be exposed directly to the internet. However, many folks prefer to have a reverse proxy handle connections from the outside instead. This can also give greater control over TLS configurations and enables some more advanced scenario's like asset caching.
+
+## General procedure
+
+In order to use a reverse-proxy, you'll typically want to do a few things:
+
+* Configure some way to get TLS certificates for the host domain
+* Bind GoToSocial to a local IP instead of a public IP and a non-priviledged port. Adjust the `bind-address` and `port` configuration options
+* Disable Lets Encrypt in GoToSocial if you were using it. Set `letsencrypt-enabled` to `false`
+* Configure the reverse proxy to handle TLS and proxy requests to GoToSocial
+
+!!! warning
+    Do not change the value of the `host` configuration option. This needs to remain the actual domain name the instance is running on as seen by other instances on the internet. Instead, change the `bind-address` and update the `port` and `trusted-proxies`.
+
+### Container
+
+When you deploy GoToSocial using our [example Docker Compose guide](../installation/container.md), it will bind to port `443` by default as it assumes you want to directly expose it to the internet. In order to run it behind a reverse proxy, you need to change that.
+
+In the compose file:
+
+* Comment out the `- "443:8080"` line in the `ports` definition
+* If you had enabled Lets Encrypt support:
+    * Comment out the `- "80:80"` line in the `ports` definition
+    * Set `GTS_LETSENCRYPT_ENABLED` back to `"false"` or comment it out
+* Uncomment the `- "127.0.0.1:8080:8080"` line instead
+
+This now causes Docker to only forward connections on `127.0.0.1` on port `8080` to the container, effectively isolating it from the outside world. You can now tell your reverse-proxy to send requests there instead.
+
+## Guides
+
+We have guides available for the following servers:
+
+* [nginx](nginx.md)
+* [Apache httpd](apache-httpd.md)
+* [Caddy 2](caddy.md)
+
+## WebSockets
+
+When using a reverse-proxy, special care must be taken to allow WebSockets to work too. This is necessary as many client applications use WebSockets to stream your timeline. WebSockets is not used as part of federation.
+
+Make sure you read the [WebSocket](websocket.md) documentation and configure your reverse proxy accordingly.
diff --git a/docs/getting_started/reverse_proxy/nginx.md b/docs/getting_started/reverse_proxy/nginx.md
new file mode 100644
index 000000000..377f2ef02
--- /dev/null
+++ b/docs/getting_started/reverse_proxy/nginx.md
@@ -0,0 +1,186 @@
+# NGINX
+
+## Requirements
+
+For this you will need [Certbot](https://certbot.eff.org/), the Certbot NGINX plugin and of course [NGINX](https://www.nginx.com/) itself.
+
+These are popular packages so your distro will probably have them.
+
+### Ubuntu
+
+```bash
+sudo apt install certbot python3-certbot-nginx nginx
+```
+
+### Arch
+
+```bash
+sudo pacman -S certbot certbot-nginx nginx
+```
+
+### OpenSuse
+
+```bash
+sudo zypper install nginx python3-certbot python3-certbot-nginx
+```
+
+## Configure GoToSocial
+
+If GoToSocial is already running, stop it.
+
+```bash
+sudo systemctl stop gotosocial
+```
+
+Or if you don't have a systemd service just stop it manually.
+
+In your GoToSocial config turn off letsencrypt by setting `letsencrypt-enabled` to `false`.
+
+If you we running GoToSocial on port 443, change the `port` value back to the default `8080`.
+
+If the reverse proxy will be running on the same machine, set the `bind-address` to `"localhost"` so that the GoToSocial server is only accessible via loopback. Otherwise it may be possible to bypass your proxy by connecting to GoToSocial directly, which might be undesirable.
+
+## Set up NGINX
+
+First we will set up NGINX to serve GoToSocial as unsecured http and then use Certbot to automatically upgrade it to serve https.
+
+Please do not try to use it until that's done or you'll risk transmitting passwords over clear text, or breaking federation.
+
+First we'll write a configuration for NGINX and put it in `/etc/nginx/sites-available`.
+
+```bash
+sudo mkdir -p /etc/nginx/sites-available
+sudoedit /etc/nginx/sites-available/yourgotosocial.url.conf
+```
+
+In the above commands, replace `yourgotosocial.url` with your actual GoToSocial host value. So if your `host` is set to `example.org`, then the file should be called `/etc/nginx/sites-available/example.org.conf`
+
+The file you're about to create should look like this:
+
+```nginx.conf
+server {
+  listen 80;
+  listen [::]:80;
+  server_name example.org;
+  location / {
+    # set to 127.0.0.1 instead of localhost to work around https://stackoverflow.com/a/52550758
+    proxy_pass http://127.0.0.1:8080;
+    proxy_set_header Host $host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+  client_max_body_size 40M;
+}
+```
+
+Change `proxy_pass` to the ip and port that you're actually serving GoToSocial on (if it's not on `127.0.0.1:8080`), and change `server_name` to your own domain name.
+
+If your domain name is `example.org` then `server_name example.org;` 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 `proxy_pass http://192.168.178.69:8080;` would be the correct value.
+
+**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 GoToSocial use the same server name. If not, GoToSocial will build the wrong authentication headers, and all attempts at federation will be rejected with 401.
+
+**Note**: The `Connection` and `Upgrade` headers are used for WebSocket connections. See the [WebSocket docs](websocket.md).
+
+**Note**: `client_max_body_size` is set to 40M in this example, which is the default max video upload size for GoToSocial. You can make this value larger or smaller if necessary. The nginx default is only 1M, which is rather too small.
+
+**Note**: To make `X-Forwarded-For` and rate limiting work, set the `trusted-proxies` configuration variable. See the [rate limiting](../../api/ratelimiting.md) and [general configuration](../../configuration/general.md) docs
+
+Next we'll need to link the file we just created to the folder that nginx reads configurations for active sites from.
+
+```bash
+sudo mkdir -p /etc/nginx/sites-enabled
+sudo ln -s /etc/nginx/sites-available/yourgotosocial.url.conf /etc/nginx/sites-enabled/
+```
+
+Again, replace `yourgotosocial.url` with your actual GoToSocial host value.
+
+Now check for configuration errors.
+
+```bash
+sudo nginx -t
+```
+
+If everything is fine you should get this as output:
+
+```text
+nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
+nginx: configuration file /etc/nginx/nginx.conf test is successful
+```
+
+Everything working? Great! Then restart nginx to load your new config file.
+
+```bash
+sudo systemctl restart nginx
+```
+
+## Setting up SSL with certbot
+
+You should now be able to run certbot and it will guide you through the steps required to enable https for your instance.
+
+```bash
+sudo certbot --nginx
+```
+
+After you do, it should have automatically edited your configuration file to enable https.
+
+Reload NGINX one last time:
+
+```bash
+sudo systemctl restart nginx
+```
+
+Now start GoToSocial again:
+
+```bash
+sudo systemctl start gotosocial
+```
+
+## Results
+
+You should now be able to open the splash page for your instance in your web browser, and will see that it runs under https!
+
+If you open the NGINX config again, you'll see that Certbot added some extra lines to it.
+
+**Note**: This may look a bit different depending on the options you chose while setting up Certbot, and the NGINX version you're using.
+
+```nginx.conf
+server {
+  server_name example.org;
+  location / {
+    # set to 127.0.0.1 instead of localhost to work around https://stackoverflow.com/a/52550758
+    proxy_pass http://127.0.0.1:8080;
+    proxy_set_header Host $host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+  client_max_body_size 40M;
+
+  listen [::]:443 ssl ipv6only=on; # managed by Certbot
+  listen 443 ssl; # managed by Certbot
+  ssl_certificate /etc/letsencrypt/live/example.org/fullchain.pem; # managed by Certbot
+  ssl_certificate_key /etc/letsencrypt/live/example.org/privkey.pem; # managed by Certbot
+  include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
+  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
+}
+
+server {
+  if ($host = example.org) {
+      return 301 https://$host$request_uri;
+  } # managed by Certbot
+
+  listen 80;
+  listen [::]:80;
+  server_name example.org;
+    return 404; # managed by Certbot
+}
+```
+
+A number of additional configurations for nginx, including static asset serving and caching, are documented in the [Advanced](../advanced.md) section of our documentation.
diff --git a/docs/getting_started/reverse_proxy/websocket.md b/docs/getting_started/reverse_proxy/websocket.md
new file mode 100644
index 000000000..ec7c107a9
--- /dev/null
+++ b/docs/getting_started/reverse_proxy/websocket.md
@@ -0,0 +1,43 @@
+# WebSocket
+
+GoToSocial uses the secure [WebSocket protocol](https://en.wikipedia.org/wiki/WebSocket) (aka `wss`) to allow for streaming updates of statuses and notifications via client apps like Semaphore.
+
+In order to use this functionality, you need to ensure that whatever proxy you've configured GoToSocial to run behind allows WebSocket connections through.
+
+The WebSocket endpoint is located at `wss://example.org/api/v1/streaming` where `example.org` is the hostname of your GoToSocial instance.
+
+The WebSocket endpoint uses the same port as configured in the `port` section of your [general config](../../configuration/general.md).
+
+Typical WebSocket **request** headers as sent by Pinafore look like the following:
+
+```text
+Host: example.org
+User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:99.0) Gecko/20100101 Firefox/99.0
+Accept: */*
+Accept-Language: en-US,en;q=0.5
+Accept-Encoding: gzip, deflate, br
+Sec-WebSocket-Version: 13
+Origin: https://pinafore.social
+Sec-WebSocket-Protocol: null
+Sec-WebSocket-Extensions: permessage-deflate
+Sec-WebSocket-Key: YWFhYWFhYm9vYmllcwo=
+DNT: 1
+Connection: keep-alive, Upgrade
+Sec-Fetch-Dest: websocket
+Sec-Fetch-Mode: websocket
+Sec-Fetch-Site: cross-site
+Pragma: no-cache
+Cache-Control: no-cache
+Upgrade: websocket
+```
+
+Typical WebSocket **response** headers as returned by GoToSocial look like the following:
+
+```text
+HTTP/1.1 101 Switching Protocols
+Upgrade: websocket
+Connection: Upgrade
+Sec-WebSocket-Accept: WVdGaFlXRmhZbTl2WW1sbGN3bz0K
+```
+
+Whatever your setup, you need to ensure that these headers are allowed through your proxy, which may require extra configuration depending on the exact proxy being used.