Configure a reverse proxy for The Lounge

In this page:

  1. Nginx
  2. Apache
  3. Caddy
  4. HAProxy
  5. Cloudflare
  6. Redbird with Let’s Encrypt

Serving The Lounge through a reverse proxy instead of the built-in HTTP server comes with a few benefits:

  • The Lounge needs to run as root in order to serve it on port 80 (or 443 for HTTPS), or you must always type the port number as part of the URL. Reverse proxies usually abstract this, take control of ports 80 and 443, then redirect traffic to The Lounge.

  • If the built-in HTTP server is already listening to port 80 or 443, it means that your server cannot serve any other project through these ports. Reverse proxies act as “gates” that route traffic from ports 80 and 443 to the requested service.

  • While The Lounge comes with HTTPS support out of the box, any changes to the HTTPS certificates (such as renewing them) requires a server restart. Using a reverse proxy lets you reload the reverse proxy without having to restart The Lounge.

  • When serving a website with HTTPS, it is common to also serve an HTTP counterpart that redirects to the HTTPS version. This is not possible with the built-in server that listens to a single port. It is usually trivial to do so with reverse proxies.

It however requires more configuration than just relying on the built-in server, so this guide helps going through the extra complexity.

This document assumes that your The Lounge is available on host 127.0.0.1 and port 9000.

Nginx

location / {
	proxy_pass http://127.0.0.1:9000/;
	proxy_http_version 1.1;
	proxy_set_header Connection "upgrade";
	proxy_set_header Upgrade $http_upgrade;
	proxy_set_header X-Forwarded-For $remote_addr;
	proxy_set_header X-Forwarded-Proto $scheme;

	# by default nginx times out connections in one minute
	proxy_read_timeout 1d;
}

If you want to access The Lounge in a sub folder, change the first line to location ^~ /irc/ {

File uploads

If you have file uploads enabled in The Lounge, you may hit an issue when going over nginx’s default upload limit, which will result in a 413 (Request Entity Too Large) error. To prevent this from happening, disable or increase client_max_body_size variable.

If you have set baseUrl option, then you will need to add extra configuration to proxy the upload urls. For example, if you set baseURL to https://example.com/folder/ then you need to add location /folder/ to your nginx configuration:

location /folder/ {
	proxy_pass http://127.0.0.1:9000/uploads/;
	proxy_set_header X-Forwarded-For $remote_addr;
}

PageSpeed

If you use the PageSpeed module, then it may break The Lounge, and you should turn it off by adding pagespeed off; to your configuration. The Lounge is already optimized, and pagespeed will have no effect on it.

Compression

If you do not have GZIP compression already configured in Nginx, we suggest adding this basic configuration.

Apache

Enable the necessary modules a2enmod rewrite, a2enmod proxy, a2enmod proxy_http, and a2enmod proxy_wstunnel.

RewriteEngine On
RewriteCond %{REQUEST_URI}  ^/socket.io            [NC]
RewriteCond %{QUERY_STRING} transport=websocket    [NC]
RewriteRule /(.*)           ws://127.0.0.1:9000/$1 [P,L]

RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
ProxyVia On
ProxyRequests Off
ProxyAddHeaders On
ProxyPass / http://127.0.0.1:9000/
ProxyPassReverse / http://127.0.0.1:9000/

# By default Apache times out connections after one minute,
# set to 86400 seconds (1 day) instead
ProxyTimeout 86400

If you want to access The Lounge in a sub folder, use the following configuration:

RewriteEngine On
RewriteRule ^/irc$ /irc/ [R]
RewriteCond %{REQUEST_URI}  ^/irc/socket.io        [NC]
RewriteCond %{QUERY_STRING} transport=websocket    [NC]
RewriteRule /irc/(.*)       ws://127.0.0.1:9000/$1 [P,L]

RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
ProxyVia On
ProxyRequests Off
ProxyAddHeaders On
ProxyPass /irc/ http://127.0.0.1:9000/
ProxyPassReverse /irc/ http://127.0.0.1:9000/

# By default Apache times out connections after one minute,
# set to 86400 seconds (1 day) instead
ProxyTimeout 86400

Caddy

Caddy v1

proxy / http://127.0.0.1:9000 {
	transparent
	websocket
}

File uploads

If you have set baseUrl option, then you will need to add extra configuration to proxy the upload urls.

proxy /folder/ http://127.0.0.1:9000/uploads {
	without /folder
	transparent
}

Caddy v2

reverse_proxy http://127.0.0.1:9000

If you want to access The Lounge in a sub folder, use the following configuration:

route /irc/* {
	uri strip_prefix /irc
	reverse_proxy http://127.0.0.1:9000
}

HAProxy

frontend  main
	bind *:1000
	option forwardfor
	http-request set-header X-Forwarded-Proto https if { ssl_fc }
	acl thelounge_site   hdr(host)  thelounge.example.com
	use_backend thelounge       if thelounge_site

backend thelounge
	server thelounge 127.0.0.1:9000

Cloudflare

The following page rules need to be set in order to use the Cloudflare DNS with The Lounge:

  • Rocket Loader set to Off
  • Disable Apps

Whenever you update The Lounge, you will have to purge cache in your Cloudflare dashboard for your browser to correctly receive updated files.

Redbird with Let’s Encrypt

First, install Redbird:

yarn add redbird

Then, create a file named proxy.js and edit it with:

const redbird = require("redbird")({
	port: 80, // Port to listen HTTP connections
	letsencrypt: {
		path: __dirname + "/certs/", // Certificates will be saved, updated and archived there
	},
	ssl: {
		port: 443, // Port to listen HTTPS connections
	},
});

redbird.register("example.com", "http://127.0.0.1:9000", {
	ssl: {
		letsencrypt: {
			email: "mail@example.com", // Must be a host with MX record
			production: true, // WARNING: Only use this flag when the proxy is verified to work correctly to avoid being banned!
		}
	}
});

You can then run it with node proxy.js.