Instructions how to use netbird in a homelab with local IP + free domain + certificated from duckdns

[egandro]

These are my instructions on how to install netbird in your homelab or for testing purpose.

This requires no public ip. You get a free duckdns domain, it uses your homelabs 192,x,.x.x. IP, it also comes with a letsencrypt certificate.

Please ping me and I'll make a PR for this.

DuckDNS

• create a VM (debian, ubuntu, ...) e.g. in proxmox or similar (ensure a static IP or pin the IP in your DHCP Server)
  • e.g. vm IP = 192.168.10.2
• create an account / login at duckdns.org
• create a new host e.g. testbird.duckdns.org - put it to 192.168.10.2
• copy the duckdns token

Know issues:

• duckdns is free - so it can be a big pain!
• it might take some time to update any change of duckdns to your local DNS
• you might have a local router / DNS setup with enabled "Rebind protection" please fix this
• From the OpenWRT Manual:
  • Discard upstream responses containing RFC1918 addresses.
  • Discard also upstream responses containing RFC4193, Link-Local and private IPv4-Mapped RFC4291 IPv6 Addresses.

Login to your VM and install docker + jq

export NETBIRD_DOMAIN=testbird.duckdns.org
export DUCKDNS_TOKEN=<token from duckdns>

# this might not give you the real ip but it's a nice test
VM_IP=$(hostname --ip-address)
echo $VM_IP
# this needs to resolve and ping your private VM's ip
ping -c 3 $NETBIRD_DOMAIN

mkdir -p netbird
cd netbird
curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh

# use caddy image with duckdns support <https://github.com/caddy-dns/duckdns>
sed -i 's|image: caddy|image: serfriz/caddy-duckdns|g' getting-started-with-zitadel.sh

# use the internal IP as "external IP"
sed -i "s|IP=\$(curl -s -4 https://jsonip.com \| jq -r '.ip')|IP=$VM_IP|" getting-started-with-zitadel.sh

# use duckdns ACME via DNS challenge
sed -i "/:80\${CADDY_SECURE_DOMAIN} {/a \
        tls {\n\
                dns duckdns ${DUCKDNS_TOKEN} {\n\
                        override_domain ${NETBIRD_DOMAIN}\n\
                }\n\
        }" getting-started-with-zitadel.sh

bash getting-started-with-zitadel.sh

Patience is key! Letsencrypt and duckdns can be slow. It can fail for a long time.

You can run on a 2nd console: docker compose logs -f | grep -i letsencrypt

If anything is wrong this is how you can reset it:

docker compose down -v --remove-orphans
cd ..
rm -rf nerdbird

Please note: letsencrypt might block you if you trigger to many certificates, just go with a new domain name
or use a prefix prefix it e.g. export NETBIRD_DOMAIN=prefix1.testbird.duckdns.org