Docker-Compose: ZeroTier Controller, WUI, Router

readme.md

Instructions

Initial Setup:

Update NEXTAUTH_URL in the docker-compose.yml to the IP address you will use to access the ztnet web ui.

This is important or you will not be able to login. Generally you'll want to set it to your machine's LAN IP address.

Start everything with:

docker-compose up -d

Wait a few minutes for the database to be setup. It should take around 2 minutes. If you want to check, you can check with docker-compose logs and see if ztnet has said The seed command has been executed.. Any errors after this can be ignored.

Run

docker exec -it $(docker ps | grep zt-controller | head -n 1 | cut -d ' ' -f1) cat /var/lib/zerotier-one/authtoken.secret

To get the API key for your controller.

Open the WebUI, signup, login and then navigate to the ZT Controller menu.

Click Change on the Zerotier Secret field and place in the API key from the step above and click submit.

Click Change on the Local Zerotier URL field and place in http://zt-controller:9993 and click submit.

You should now see some of the errors on that screen disappear and see that it is communicating with the controller.

Joining the router to a network

In the WebUI, create a new network by clicking on Local Controller and then Create a netowrk. A ID will be automatically generated, it'll look something like 8056c2e21c000001.

Run the following command:

docker exec $(docker ps | grep zt-router | head -n 1 | cut -d ' ' -f1) zerotier-cli join 8056c2e21c000001

Be sure to update 8056c2e21c000001 with the actual network ID you created.

In the WebUI, inside the network's detail page (Can be accessed by clicking the network), scroll down to Network Members. You should see your router there. Click the Auth checkbox to grant it access. New network members must be approved the same way.

Restart the stack after joining and granting access to the network:

docker-compose down
docker-compose up

Common issues:

Check that the network interface on your host matches one of the ones under zerotier-router.environment["ZEROTIER_ONE_LOCAL_PHYS"]. You can do this by running either iconfig or ip addr on the host machine.

Debugging:

Exec shell into a container:

docker exec -it $(docker ps | grep sinamics/ztnet | head -n 1 | cut -d ' ' -f1) /bin/bash
docker exec -it $(docker ps | grep zerotier-controller | head -n 1 | cut -d ' ' -f1) /bin/sh
docker exec -it $(docker ps | grep zerotier-router | head -n 1 | cut -d ' ' -f1) /bin/sh

docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:15.5-alpine
    container_name: postgres-zt
    volumes:
      - ./volumes/postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ztnet
      POSTGRES_USER: ztnetuser
      POSTGRES_PASSWORD: %DB_PASSWORD%
    restart: unless-stopped
    networks:
      - app-network

  ztnet-zt:
    image: sinamics/ztnet:0.5.10
    container_name: ztnet-zt
    depends_on:
      - postgres
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_PORT: "5432"
      POSTGRES_DB: ztnet
      POSTGRES_USER: ztnetuser
      POSTGRES_PASSWORD: %DB_PASSWORD%
      NEXTAUTH_SECRET: %NEXT_AUTH_SECRET%
      # Run `docker exec -it $(docker ps | grep zt-controller | head -n 1 | cut -d ' ' -f1) cat /var/lib/zerotier-one/authtoken.secret` while the container is running to get the secret.
      # This can also be entered in the web interface.
      # ZT_SECRET: ZT_CONTROLLER_SECRET.
      NEXTAUTH_URL: "http://YOUR_ZEROTIER_IP:3000" # IMPORTANT!!! Update this
    ports:
      - "3000:3000"
    restart: unless-stopped
    networks:
      - app-network

  ztnet-lan:
    image: sinamics/ztnet:0.5.10
    container_name: ztnet-lan
    depends_on:
      - postgres
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_PORT: "5432"
      POSTGRES_DB: ztnet
      POSTGRES_USER: ztnetuser
      POSTGRES_PASSWORD: %DB_PASSWORD%
      NEXTAUTH_SECRET: %NEXT_AUTH_SECRET%
      # Run `docker exec -it $(docker ps | grep zt-controller | head -n 1 | cut -d ' ' -f1) cat /var/lib/zerotier-one/authtoken.secret` while the container is running to get the secret.
      # This can also be entered in the web interface.
      # ZT_SECRET: ZT_CONTROLLER_SECRET.
      NEXTAUTH_URL: "http://YOUR_LAN_IP:3001" # IMPORTANT!!! Update this
    ports:
      - "3001:3000"
    restart: unless-stopped
    networks:
      - app-network

  zerotier-controller:
    image: zyclonite/zerotier:1.12.2
    container_name: zt-controller
    environment:
      ZT_ENABLE_CONTROLLER: 'true'
      ZT_ALLOW_MANAGEMENT_FROM: "0.0.0.0/0"
    volumes:
      - ./volumes/zt-controller:/var/lib/zerotier-one
    ports:
      - "9993:9993/udp"
    restart: unless-stopped
    networks:
      - app-network

  zerotier-router:
    image: zyclonite/zerotier:router-1.12.2
    container_name: zt-router
    environment:
      ZEROTIER_ONE_LOCAL_PHYS: "eno1 eth0 wlan0" # You  may need to adjust this
      ZEROTIER_ONE_USE_IPTABLES_NFT: 'true'
      ZEROTIER_ONE_GATEWAY_MODE: "both"
    cap_add:
      - NET_ADMIN
      - SYS_ADMIN
      - NET_RAW
    devices:
      - /dev/net/tun:/dev/net/tun
    # environment:
      # ZT_NETWORK_ID: your-network-id-here  # Replace with your actual ZeroTier network ID. You must create a network in the ZeroTier web interface first.
    volumes:
      - ./volumes/zt-router:/var/lib/zerotier-one
    restart: unless-stopped
    depends_on:
      - zerotier-controller

networks:
  app-network:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.31.255.0/29