Netmaker admin server

Ready?

At this point You should have an Alpine server with a public-facing IP address terraformed and set up with Ansible, which means Your firewall rules are also in place. (You can start Your journey here if that is not true.)

Setup

Pull my infra repository. You have done this before on Your machine, but this time do it on the VPS.

doas apk add git
git clone https://git.sr.ht/~voroskoi/infra

There are two directories there named after my hostnames. Do not worry, You do not have to use those names, feel free to change them.

kistasli is the VPS machine. Until now we have used the files in this directory, it is time to switch to the docker subdir.

From now on I will assume that You are in the infra/kistasli/docker directory on the VPS.

Setup docker environment

Open .env in Your favourite editor:

HOSTNAME=voroskoi.duckdns.org
HOST_IP=139.144.72.56

Change these values. HOST_IP is the external IP address of the VPS. HOSTNAME is the hostname You would like to use with Netmaker. This has to be a real hostname, as You need an SSL certificate for it.

Get a domain (if You do not have one already)

Free version

As You can see I just use duckdns.org as my domain name. You can register 5 subdomains there. There are plenty other similar services. Netmaker uses a sub-subdomain, so that does not count.

Buy a domain

I also bought one, maybe I will use it for email, not sure yet. There are also plenty of domain registrar out there. I went with porkbun.com, which is fine, but feel free to chose other.

Setup DNS records for Your domain

DuckDNS

If You use duckdns.org You can not setup DNS records, but You do not have to either, it will work fine.

Other

In these examples You own the domain mydomain.com

If You use some other DNS make sure You setup the following:

  • An A record (IPv4) pointing to the VPS IP address as mydomain.com. (Netmaker actually do not need this, just good to have for ssh and such.)
  • A CNAME record forwarding www.mydomain.com to mydomain.com. (Still not for Netmaker.)
  • An A record (IPv4) pointing to the VPS IP address as *.netmaker.mydomain.com.
  • Please do not setup an AAAA (IPv6) record yet. IPv6 is disabled on Your firewall, so does not make sense and can cause certificate registering problems. You can do this later.

Setup passwords

Create a directory called secrets within the docker directory. You have to create 2 files there: nm_m_key.txt and mq_admin_pw.txt. The content of the file is Your Netmaker MASTER_KEY and MQ_ADMIN_PASSWORD. Please make sure You save them somewhere safe and adjust file permissions.

This is an actual setup, not a template

WARNING: Those files in infra are my actual config files, not intended for anybody as is (except me).

For Netmaker admin server You only need mq, netmaker, netmaker-ui and traefik. Those should work fine for anybody.

Other services use my credentials, You have to edit those:

  • Netclient will not work with the TOKEN set in the file, as that is for my server (and I made sure it is revoked).
  • Adguard would also use my setup, which You probably do not want and my password is set (which You do not know, sorry).

Let’s Encrypt staging

Let’s Encrypt is rate limited. If if fails too many times for Your domain it will just disable it temporary (maybe days). While I was working on Netmaker 0.16 -> 0.16.1 upgrade I managed to disable my domain, actually this is my I use duckdns.org despite having a real DNS name.

To avoid this look for these lines in traefik config in docker-compose.yml:

# use staging server for testing new setups
# - "--certificatesresolvers.http.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

Remove # at the beginning of the second line to use the staging server. Those certs are invalid, but You can check that the certificate acquiring process itself work without messing everything up. Once You are satisfied with the results:

  • Stop traefik or the whole docker-compose
  • Put back the # You just removed.
  • Remove letsencrypt/acme.json
  • Restart traefik (or whole docker-compose)

Fire up Netmaker

If You use Let’s Encrypt staging (recommended) it will not work for the first time, do not worry.

docker-compose up

It will fill the screen with various log messages from those containers. You can stop it with Ctrl-C, but just do not do that yet.

You should check the following:

  1. Traefik should not log any error regarding ACME fails. If You do not get the certificates You have to fix that first.
  2. If there is no error, check letsencrypt/acme.json, see if all 3 subdomain (api, broker, dashboard) got its certificate.
  3. If broker is missing, it is because netmaker waits for mq and mq waits for netmaker and does not start up. Comment the following line in the mq container and restart docker-compose. Now You should have all 3 certs (You may have to do this with the non-staging too!) Do not forget the re-enable that line after this hack works out!
command: ["/mosquitto/config/wait.sh"]
  1. When You have all 3 certificates, switch to the real CA server as described before. Check that all 3 certificates are there. If broker is missing do the hack from the previous point again. If You have the certificates that is a good sign.

Now, You should see something similar in mq logs:

mosquitto version 2.0.11 running
New connection from 172.21.0.2:34004 on port 1883.
New client connected from 172.21.0.2:34004 as L0vUDgN0IZFru9VaS6HoRL5 (p2, c1, k60, u'Netmaker-Admin').
New connection from 172.21.0.2:34006 on port 1883.
New client connected from 172.21.0.2:34006 as ydmOjmIcw9nNaT1GB1q97Se (p2, c1, k60, u'Netmaker-Server').

Try opening dashboard.netmaker.mydomain.com in Your browser. See setup instructions here.

In the final part I will show You my setup as an example with real values, so You can adapt that to Your needs.