Skip to content

Commit

Permalink
[docs] Update Apache2 HTTP Server docs for websockets (#934)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tsmethurst
tsmethurst authored Oct 31, 2022
1 parent c0a2d70 commit 972bd17
Showing 1 changed file with 49 additions and 45 deletions.
94 changes: 49 additions & 45 deletions docs/installation_guide/apache-httpd.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
# Reverse proxy with Apache httpd
# Reverse proxy with Apache HTTP Server

## Requirements

For this you will need Apache httpd server.
For this you will need the Apache HTTP Server.

That is a fairly popular package so your distro will probably have it.

### Ubuntu
Expand All @@ -23,10 +24,19 @@ sudo pacman -S apache
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 proxy_wstunnel
```

## Configure GoToSocial

In your GoToSocial config turn off letsencrypt.
First open the file in your text editor.
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
Expand All @@ -42,42 +52,57 @@ sudo systemctl restart gotosocial.service

Or if you don't have a systemd service just restart it manually.

## Set up Apache httpd
## Set up Apache HTTP Server with LetsEncrypt SSL

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.
Now we'll configure Apache HTTP Server to serve GoToSocial requests.

First we'll write a configuration for Apache httpd and put it in `/etc/apache2/sites-available`.
First we'll write a configuration for Apache HTTP Server and put it in `/etc/apache2/sites-available`:

```bash
sudo mkdir /etc/apache2/sites-available/
sudoedit /etc/apache2/sites-available/yourgotosocial.url.conf
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
<VirtualHost *:80>
MDomain example.com auto
MDCertificateAgreement accepted
<VirtualHost *:80 >
ServerName example.com
</VirtualHost>
<VirtualHost *:443>
ServerName example.com
SSLEngine On
ProxyPreserveHost On
ProxyPassMatch ^/(api/v1/streaming.*)$ ws://localhost:8080/$1
ProxyPass / http://localhost:8080/
ProxyPassReverse / http://localhost:8080/
RequestHeader set "X-Forwarded-Proto" expr=https
</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.
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://localhost:8080` to the correct address and port 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.

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.
`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.

Next we'll need to link the file we just created to the folder that Apache httpd reads configurations for active sites from.
The line `ProxyPassMatch ^/(api/v1/streaming.*)$ ws://localhost:8080/$1` ensures that Websocket streaming connections also work. See the [websocket](./websocket.md) document for more information on this.

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/yourgotosocial.url.conf /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
Expand All @@ -90,40 +115,19 @@ If everything is fine you should get this as output:
Syntax OK
```

Everything working? Great! Then restart Apache httpd to load your new config file.
Everything working? Great! Then restart Apache HTTP Server 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:
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
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>
```
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).

This allows mod_md to take care of the SSL setup, and it will also redirect from http to https.
After we put this into place, we'll need to restart Apache httpd

```bash
sudo systemctl restart apache2
```
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`

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!
If this happens, you'll need to do one (or all) of the below:

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.
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 [email protected]` below the `MDomain` line in `/etc/apache2/sites-available/example.com.conf`, replacing `[email protected]` with a valid email address, and `example.com` with your GtS host name.

0 comments on commit 972bd17

Please sign in to comment.