Local Home Lab DNS Setup with DNSMasq and NGINX

Manage DNS for containers and applications in a Home lab setup with DNSMasq and NGINX

As I set up an increased number of FOSS applications, containers(Docker and LXD), and virtual machines built using multipass and LXD in my home lab environment, I started to realize the difficulty in remembering the different ports the applications and containers are running on. One of the solutions to address this problem was to have a Domain Name System for the local network which works for resolving local and external addresses with a reverse proxy to redirect calls based on DNS resolution so that one doesn't have to remember IP addresses and port numbers.

The below command lists the Docker Containers and ports the container are running on, the requirement is to create a domain for home setup homelab.net and access the containerized applications hosted using Domain URL e.g. appsmith.homelab.net excalidraw.homelab.net typesense.homelab.net nocodb.homelab.net etc.


# get container names and port numbers
docker container ls --format "table {{.ID}}\t{{.Names}}\t{{.Ports}}" -a


CONTAINER ID   NAMES                        PORTS
cbb2ac402270   appsmith                     0.0.0.0:9001->9001/tcp, 0.0.0.0:70->80/tcp, 0.0.0.0:444->443/tcp
c9875323b989   typesense_typesense-1_1      0.0.0.0:8108->8108/tcp
c453288c8496   excalidraw                   0.0.0.0:3001->80/tcp
5be5d33f1f50   k8s-control-plane            127.0.0.1:34589->6443/tcp
4140d2fbf7d5   mysql_nocodb_1               0.0.0.0:8082->8080/tcp
e7310461bee9   mysql_root_db_1              3306/tcp, 33060/tcp
9b56c33d45d5   meilisearch_ms_1             0.0.0.0:7700->7700/tcp
9ac6a0e16b0e   mongo2                       0.0.0.0:20002->27017/tcp
2aaf01d2233f   mongo1                       0.0.0.0:20001->27017/tcp
860b521f97dc   mongo3                       0.0.0.0:20003->27017/tcp
d8ad1ec3cab8   rethinkdb_rethinkdb_1        0.0.0.0:28015->28015/tcp, 0.0.0.0:29015->29015/tcp, 0.0.0.0:8081->8080/tcp

The containers and applications running on the local home network as shown above do not have a public domain name, the option was to look for setting up a DNS server using DNSMasq and NGINX as a reverse proxy. The containers may not be the only use case scenario for local DNS server, there could be many others like accessing a local file share across devices; accessing applications from a mobile device, sharing a printer

The options to access container applications before implementing DNSMasq and NGINX

appsmith - localhost:70 excalidraw - localhost:80 typesense - localhost:8080

after implementation of DNSMasq and NGINX

appsmith - appsmith.homelab.net excalidraw - excalidraw.homelab.net typesense - typesense.homelab.net

Let us get started with the implementation steps for DNSMasq and NGINX. The below steps are performed on Ubuntu 20.04 - Debian-based distro.

Before starting the installation of DNSMasq, disable systemd-resolve which binds to port 53, the default port for DNSMasq

  sudo systemctl stop systemd-resolved
  sudo systemctl disable systemd-resolved

Step 1: Install DNSUtils, DNSMasq

  sudo apt update && sudo apt install dnsmasq && sudo apt install dnsutils

Step 2: Create the DNSMasq configuration file

    dnsmasq_conf="no-dhcp-interface=enp2s0f0
    bogus-priv
    domain=homelab.net
    expand-hosts
    local=/homelab.net/
    domain-needed
    no-resolv
    no-poll
    server=8.8.8.8
    server=8.8.4.4"
    sudo echo -e "$dnsmasq_conf" > /etc/dnsmasq.d/home-lab.net
   sudo systemctl restart dnsmasq

Step 3: Add container DNS records in the file./etc/hosts. The records in hosts file will be used by DNSMasq for client responses

  sudo nano /etc/hosts  
  # add the below records to the hosts file
  #Container DNS records
  # appsmith
  192.168.20.113 appsmith
  # excalidraw
  192.168.20.113 excalidraw
  # typesense
  192.168.20.113 typesense

Step 4: Restart DNSMasq service

sudo systemctl restart dnsmasq.service

Step 5: Install NGINX

  sudo apt update && sudo apt install nginx

Step 6: To enable reverse proxy feature, create a new NGINX configuration file in sites-enabled directory

  sudo nano /etc/nginx/sites-enabled/homelab.conf
  server {
          listen 80;
          listen [::]:80;
          server_name typesense.homelab.net;
          location / {
                   proxy_bind 192.168.20.113;
                   proxy_pass http://localhost:3000;
          }
  }

  server {
          listen 80;
          listen [::]:80;
          server_name appsmith.homelab.net;
          location / {
                  proxy_bind 192.168.20.113;
                  proxy_pass http://localhost:70;
          }

  }

  server {
          listen 80;
          listen [::]:80;
          server_name excalidraw.homelab.net;
          location / {
                  proxy_bind 192.168.20.113;
                  proxy_pass http://localhost:3001;
          }

  }

The proxy_pass argument will forward all incoming client requests to nocodb.homelab.net to respective app. The IP address and port number can be easily changed.

Step 7 reload nginx

  sudo systemctl reload nginx