Using Caddy as a Reverse Proxy for BlueMap (and other things)

Move over, Nginx!

I like Minecraft, and I also like cool computer things. This one plugin, called BlueMap, provides a neat interactive web map of your Minecraft world, complete with live player locations.

Caution: I do not offer technical support, nor do I know if these instructions will work on your specific system. As always, trust primary sources if something here is not working. All I can say for sure is that this worked for me a little while ago.

Although BlueMap can technically be directly exposed to the internet, I chose to use what is called a Reverse Proxy, which is a type of server that looks at incoming requests and forwards them to the correct recipient, which in turn then produces a response to forward to the requester. I did this both for the purpose of separating BlueMap from the internet directly and because BlueMap does not natively support TLS, a web technology that ensures that data is secure and private while in transit between the server and the client. This is nice to have, but not strictly essential. A reverse proxy allows you to configure HTTPS/TLS between itself and the client, while still using insecure HTTP internally on your network.

I want players to be able to connect through my domain, which I manage through Cloudflare. I will go into the DNS menu and create an A record¹ that points “minecraft” to my home’s IP address,

minecraft.[mydomain].com points to [myaddress].

Note that you don’t need to have it say Minecraft first; it could just be mydomain.com, or [anything].mydomain.com. It is worth remarking that, especially for residential internet plans, the IP may change on occasion. In this case, you’ll have to go in and update it. Make sure to disable the Cloudflare proxy to DNS only, as otherwise, this both messes with the way Minecraft works and how TLS certificates work.

The A record tells the DNS resolver that it has reached its ending point, as it has resolved a domain name into an IP. It does this by recursively querying up the chain of Nameservers — which keep track of who knows what about what — until it finds a nameserver that has the A record of our domain. Explore this here, an explanation of how DNS works, and here, an interactive trace of a DNS query.

If you’ve made a Minecraft server, you will probably know where to find the port forwarding settings, which let your router know where it should send inbound traffic addressed to a certain port. You’ll need to port forward the IP of whatever server you’d like to put the reverse proxy on, henceforth assumed to be the same server as the Minecraft server, specifically for port 443.

As for what to use for a reverse proxy, the heavyweight incumbent Nginx is fine. Setup is not terribly hard, but the newer alternative, Caddy, offers a simpler setup experience and a significantly streamlined TLS system, being one of the only reverse proxies or web servers in general that do it by default.

For my example, I am using an Ubuntu 22.04LTS system, on a non-root sudoer account, which you should also do for security reasons. First, update and upgrade your system — it may come in handy:

mc_server@vm:~$ sudo apt update && sudo apt upgrade

We should also configure our firewall, as the system is okay with everything by default, which is not the greatest. This will enable the firewall if you haven’t already put one up and allow HTTPS traffic. If your Minecraft server is on the same server, also run the second command, if you haven’t already. I have bolded the command to allow port 22 (SSH), because if you are remotely accessing a machine, not doing this may lock you out of the system, which is embarrassing to do. If you are accessing it physically, then that can be safely omitted. Only forwarded ports will be exposed to the internet, so as long as you don’t have 22 forwarded, it should be okay.

mc_server@vm:~$ sudo ufw allow 443/tcp && sudo ufw allow 22/tcp && sudo ufw enable
mc_server@vm:~$ sudo ufw allow 25565/tcp
mc_server@vm:~$ sudo ufw status

Next, follow these instructions to install Caddy, or to summarize:

mc_server@vm:~$ sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
mc_server@vm:~$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
mc_server@vm:~$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
mc_server@vm:~$ sudo apt update
mc_server@vm:~$ sudo apt install caddy

Allow me to elaborate; skip if you’d rather continue

1. Installs some things you may not already have, but will need for installing the package to make sure that it is actually Caddy

2. Get the key, make it into the format it needs to be, and give it to the key manager

3. Get the repository info for apt and put it where it needs to be. If you do cat /etc/apt/sources.list.d/caddy-stable.list, note that it calls out the key from 3

4. Fetch what packages are available from the new repository

5. Install Caddy from the repository

Next, we can configure it. I am assuming that you have, somewhere on your network, a Minecraft server with the BlueMap plugin running at some known port.

Now:

mc_server@vm:~$ sudo nano /etc/caddy/Caddyfile

Or whatever your favored text editor is. You should see something like this:

# The Caddyfile is an easy way to configure your Caddy web server.
#
# Unless the file starts with a global options block, the first
# uncommented line is always the address of your site.
#
# To use your own domain name (with automatic HTTPS), first make
# sure your domain's A/AAAA DNS records are properly pointed to
# this machine's public IP, then replace ":80" below with your
# domain name.

:80 {
        # Set this path to your site's directory.
        root * /usr/share/caddy

        # Enable the static file server.
        file_server

        # Another common task is to set up a reverse proxy:
        #reverse_proxy localhost:8000

        # Or serve a PHP site through php-fpm:
        # php_fastcgi localhost:9000
}

# Refer to the Caddy docs for more information:
# https://caddyserver.com/docs/caddyfile

Change it to look like this (changes in bold):

# The Caddyfile is an easy way to configure your Caddy web server.
#
# Unless the file starts with a global options block, the first
# uncommented line is always the address of your site.
#
# To use your own domain name (with automatic HTTPS), first make
# sure your domain's A/AAAA DNS records are properly pointed to
# this machine's public IP, then replace ":80" below with your
# domain name.

subdomain.your.domain, 10.0.0.abc {
        # Set this path to your site's directory.
        #root * /usr/share/caddy

        # Enable the static file server.
        #file_server

        # Another common task is to set up a reverse proxy:
        reverse_proxy localhost:8100

        # Or serve a PHP site through php-fpm:
        # php_fastcgi localhost:9000
}

# Refer to the Caddy docs for more information:
# https://caddyserver.com/docs/caddyfile

Starting from the beginning, change the :80, which accepts any incoming requests to it on the HTTP port, to whatever you have your domain set up to, a comma, and then the internal² IP address of your server. This permits requests towards either the public domain you have specified or towards the internal IP address of the proxy server, so you can access the map if it’s hosted on your home network³.

Then, comment out the root directory and file server and uncomment the reverse_proxy, changing the port to 8100, which will then attach to the BlueMap web server. If Caddy and the Minecraft server are on different servers, use the internal IP of the Minecraft server instead of localhost.

mc_server@vm:~$ sudo systemctl reload caddy
mc_server@vm:~$ sudo systemctl status caddy

Tada! It should say something to the effect that the service is okay, and you shouldn’t see any errors on there. Give it a try with the local IP address or the other aforementioned tricks to get external access. If all works correctly, the BlueMap client should be showing, and there should be a little lock indicating that your TLS certificate is correct. Note that when you are accessing BlueMap from your internal network, it will yell about insecurity, but this is just a feature of TLS, and is irrelevant in this context. If this bothers you, append an http:// to the local IP address in your Caddyfile and reload, which waives the whole encryption thing. Alternatively, you can forego the reverse proxy entirely and simply connect directly to the BlueMap instance, and leave the reverse proxy for other, external users.

1. Find your IP with this site. Your IP is the specific number assigned to (usually) your household that all requests to and from your computer network go through — a sort of street address.

2. The internal IP is the one you use to refer to the computer on your network rather than the wider internet. Your internal IP address can be found by doing ip addr, and taking the address of something like eth0 or wlan0.

3. If you’re using a cloud server, omit this, since you don’t have local network access anyway.