Caddy - Reverse Proxy with Pi-hole Local DNS Setup

I wanted to use Caddy’s reverse proxy functionality so that I can browse to my web applications using DNS instead of an IP address with a port number. So in the case of my Homer dashboard, I browse to homer.home.arpa instead of 192.168.1.67:8080. Caddy also automatically converts the connection to a secure connection (HTTPS) which is also nice!

This is also the reason why I use the macvlan option with Docker/Podman containers as much as possible, so that each container gets its own IP address.

Home.ARPA has been specifically created to handle “home” or “small business” name queries by shunting it to “black holes” early in the hops.

Caddyfile Configuration

I’m assuming that Caddy is already running, this can be done for example via a Docker/Podman container or via a NixOS module (see below).

It is very easy to configure a local reverse proxy. Add the following to the Caddyfile:

# uncomment to debug when things aren't working the way you'd like
#{
#       debug
#}

homer.home.arpa {
        tls internal
        handle {
                reverse_proxy 192.168.xx.xx:8080
                flush_interval -1
        }
}

Adjust the following:

homer.home.arpa
Replace homer with your name and home.arpa with your top level domain. We will also need the full domain name within Pi-hole

tls internal
Use locally-trusted certificates. Please see the Caddy docs for more information

192.168.xx.xx:8080
Replace the IP address and port. In this example I use the IP address and port of my Homer container. Please see the Caddy docs for more information about the handle directive

flush_interval -1
This was needed to solve some problems but I’ll mention it anyway. Please see the Caddy docs for more information

If you are using the NixOS Caddy module, the above Caddyfile is also very easy to add decleratively to configuration.nix (I’ll give you an example with two virtual hosts):

  services.caddy = {
    enable = true;
    virtualHosts."homer.home.arpa".extraConfig = ''
        tls internal
        handle {
                reverse_proxy 192.168.xx.xx:8080 {
                    flush_interval -1
            }
          }
    '';
    virtualHosts."phpmyadmin.home.arpa".extraConfig = ''
        tls internal
        handle {
                reverse_proxy 192.168.xx.xx:8080 {
                    flush_interval -1
            }
          }
    '';
  };

Pi-hole Local DNS Configuration

The steps below assume that Pi-hole is already running.
On the Local DNS Records page you can add domain/IP associations.

1. Select in the navigation Local DNS > DNS Records
2. Add the domain, for example: homer.home.arpa with the IP address of the Caddy server or container.

It will then look like this:

Root Certificate Installation

Now if you go to homer.home.arpa in a browser, it will indicate that the connection is not trusted or will not work at all. I fixed this by having different devices and browsers trust the Caddy root certifcate.

The steps below assume that Caddy is running as a container:

1. Go to the shell inside the container with sudo podman exec -it caddy /bin/sh. If you use docker replace the command podman with docker
2. View the content of the root certificate with cat /data/caddy/pki/authorities/local/root.crt
3. Copy the contents of the root certificate into a root.crt file on your desktop, for example. Make sure you copy -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- along
4. Exit the container shell with exit

If you do not use the container you will find the root certificate in the following location (Linux): /var/lib/caddy/.local/share/caddy/pki/authorities/local/

Firefox (desktop)

1. Go to about:preferences#privacy and scroll down to Certificates and click View Certificates...
2. Within the Certificate Manager go to Authorities and choose to import the Caddy root certificate which you previously saved as root.crt.

Chrome or Vanadium (Android)

1. Make sure you can access the root.crt file through the file manager on Android. This can be done, for example, by putting the file on Google Drive, Synology Drive or Proton Drive.
2. Tap Security & privacy and then More security settings and then Encryption & credentials and then tap Install a certificate and choose for CA-Certificate.
3. Then select your Drive in the navigation and install the certificate by tapping root.crt.

Read other notes