Running Gitit behind Apache

22 September 2017

Following on from last weeks post which looked at getting started with Gitit, this post is going to look at using Apache to proxy requests to Gitit. Doing this allows you to use Apache for SSL/TLS and removes the need to include the Gitit port when accessing the wiki.

Installing Apache

On Debian Apache can be installed using apt:

sudo apt-get update
sudo apt-get install apache2

Apache should now be enabled and running, you can check this with systemctl:

$ systemctl is-enabled apache2.service
enabled
$ systemctl is-active apache2.service
active

SSL/TLS support

By default Apache is not set up for HTTPS on Debian. To enable HTTPS support run through the following steps:

Enable the mod_ssl module with a2enmod:
```
a2enmod ssl
```
Generate a self signed certificate:
```
make-ssl-cert generate-default-snakeoil --force-overwrite
```
Note: if you already have signed certificates, deploy them to the server instead.
Enable the default SSL site configuration using a2ensite:
```
a2ensite default-ssl.conf
```
Note: if you are using custom certificates you will either need to modify /etc/apache2/sites-available/default-ssl.conf, or create and enable an alternative site configuration.
Finally use systemctl to reload the Apache configuration:
```
systemctl reload apache2.service
```

Re-configuring Gitit to listen locally

Because Gitit will only be accessed via Apache, we can configure it to bind to 127.0.0.1. Start by creating a default configuration file:

gitit --print-default-config > /etc/gitit

Then update the systemd unit file to use the new config:

$ cat /etc/systemd/system/gitit.service
[Unit]
Description=Gitit wiki
After=network.target

[Service]
ExecStart=/usr/bin/gitit --config-file=/etc/gitit
WorkingDirectory=/home/gitit/wiki
User=gitit
Group=gitit

[Install]
WantedBy=multi-user.target

Finally change the address option to address: 127.0.0.1 in /etc/gitit and restart Gitit.

sed -i 's/^address: .*$/address: 127.0.0.1/' /etc/gitit
systemctl daemon-reload
systemctl restart gitit.service

Note: systemctl daemon-reload is required because /etc/systemd/system/gitit.service is cached by systemd.

If everything goes well Gitit should now be binding to 127.0.0.1. This can be verified using this ss command:

$ ss --listen 'sport = :5001'
Netid  State      Recv-Q Send-Q  Local Address:Port Peer Address:Port
tcp    LISTEN     0      10      127.0.0.1:5001     *:*

Using ProxyPass

Start by enabling the mod_proxy and mod_proxy_html modules:

a2enmod proxy proxy_http

Then create /etc/apache2/conf-available/gitit.conf with contents similar to the following:

ProxyRequests Off

<Proxy *>
  Order deny,allow
  Allow from all
</Proxy>

ProxyPass / http://127.0.0.1:5001/
ProxyPassReverse / http://127.0.0.1:5001/

Update the reset-password-message option in /etc/gitit to use https://$hostname$$resetlink$ instead of http://$hostname$:$port$$resetlink$.

sed -i \
  's|http://\$hostname\$:\$port\$\$resetlink\$|https://$hostname$$resetlink$|' \
  /etc/gitit

Finally enable the new Apache configuration, then restart Gitit and Apache:

a2enconf gitit
systemctl restart apache2.service gitit.service

If everything goes well, Apache should now be forwarding HTTP traffic to Gitit:

Diagram showing HTTP traffice between a client, Apache and
Gitit

Using /wiki/

If you're using Apache for more than just Gitit, the configuration above isn't ideal because all requests are being routed to Gitit. One way around this is to change the wiki URL from / to /wiki/ with configuration similar to the following:

ProxyRequests Off

<Proxy *>
  Order deny,allow
  Allow from all
</Proxy>

ProxyPass /wiki/ http://127.0.0.1:5001/

<Location /wiki/>
  SetOutputFilter  proxy-html
  ProxyPassReverse /
  ProxyHTMLURLMap  /   /wiki/
  ProxyHTMLDocType "<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>" XHTML
  RequestHeader unset Accept-Encoding
</Location>

With this configuration requests for https://<hostname>/wiki/* are mapped to http://127.0.0.1:5001/*. The ProxyHTMLULRMap directive is used to rewrite links before they are pass on to the client from Apache. To use this directive make sure the mod_headers and mod_proxy_html modules are loaded:

a2enmod headers proxy_html

Once the Apache configuration is ready, make the following changes to /etc/gitit:

Set compress-responses to no
Update the reset-password-message to use https://$hostname$/wiki$resetlink$

Finally restart Gitit and Apache to pick up the changes:

systemctl restart apache2.service gitit.service