criogaid/zerotier-moon repository overview

⁠zerotier-moon⁠

🐳 Possibly the smallest ZeroTier Moon image. One-step deployment for amd64, arm64 & arm/v7.

A minimal Alpine-based image that builds ZeroTierOne directly from source. Current compressed image sizes are approximately 7.3-11.8 MiB, depending on architecture.

⁠Highlights

• Multi-architecture: linux/amd64, linux/arm64, linux/arm/v7
• Built from source: every architecture uses the same upstream ZeroTierOne release
• Minimal runtime: Alpine Linux with only the required runtime libraries
• One-step setup: automatically creates the identity and Moon configuration
• Automatic IP detection: IPv4 and IPv6 can be detected when omitted
• Persistent identity: keeps the same Moon ID across container upgrades
• Endpoint recovery: regenerates the Moon configuration when the IP or port changes
• Built-in health check: reports healthy only when ZeroTier is ONLINE
• Automatic updates: daily checks for new ZeroTierOne releases

⁠Quick Start

The following command automatically detects the public IPv4 and IPv6 addresses:

docker run -d \
  --name zerotier-moon \
  --restart unless-stopped \
  -p 9993:9993/udp \
  -v ./zerotier-one:/var/lib/zerotier-one \
  --device /dev/net/tun \
  --cap-add NET_ADMIN \
  --cap-add SYS_ADMIN \
  criogaid/zerotier-moon:latest

To specify the public endpoints explicitly:

docker run -d \
  --name zerotier-moon \
  --restart unless-stopped \
  -p 9993:9993/udp \
  -v ./zerotier-one:/var/lib/zerotier-one \
  --device /dev/net/tun \
  --cap-add NET_ADMIN \
  --cap-add SYS_ADMIN \
  criogaid/zerotier-moon:latest \
  -4 YOUR_PUBLIC_IPV4 \
  -6 YOUR_PUBLIC_IPV6 \
  -p 9993

You may omit either -4 or -6 when that address family is unavailable. If both are omitted, the container attempts automatic detection.

The advertised endpoint must be reachable by ZeroTier peers. If the host is behind NAT, forward the configured UDP port to the container host.

⁠Parameters

Ports must be between 1 and 65535. CIDR notation is not accepted.

⁠Docker Compose

services:
  zerotier-moon:
    image: criogaid/zerotier-moon:latest
    container_name: zerotier-moon
    restart: unless-stopped

    ports:
      - "9993:9993/udp"

    volumes:
      - ./zerotier-one:/var/lib/zerotier-one

    devices:
      - /dev/net/tun

    cap_add:
      - NET_ADMIN
      - SYS_ADMIN

    environment:
      # Optional: space-separated 16-character hexadecimal network IDs.
      ZEROTIER_JOIN_NETWORKS: ""

      # Optional: custom local ZeroTier API token.
      ZEROTIER_API_SECRET: ""

      # Optional: provide both values to use a custom identity.
      ZEROTIER_IDENTITY_PUBLIC: ""
      ZEROTIER_IDENTITY_SECRET: ""

    # Remove this section to use automatic IP detection.
    command:
      - "-4"
      - "YOUR_PUBLIC_IPV4"
      # Add these two entries when IPv6 is available:
      # - "-6"
      # - "YOUR_PUBLIC_IPV6"
      - "-p"
      - "9993"

Start the service:

docker compose up -d

Check its status:

docker compose ps
docker compose logs zerotier-moon

⁠Joining Networks

Joining a network is optional and is not required for Moon operation.

Set ZEROTIER_JOIN_NETWORKS to one or more space-separated network IDs:

environment:
  ZEROTIER_JOIN_NETWORKS: "8888888888888888 6666666666666666"

Each network ID must contain exactly 16 hexadecimal characters.

⁠Persistent State

Mount /var/lib/zerotier-one to preserve:

• ZeroTier identity and Moon ID
• Generated moon.json
• Generated .moon file
• Joined network configuration
• Local API authentication token

When the effective IPv4, IPv6, or port changes, the image automatically regenerates the local Moon configuration while preserving the existing identity and Moon ID.

If automatic IP detection temporarily fails, a valid persisted endpoint for that address family is retained and updated to use the currently configured port.

⁠Log Output

A successful first startup produces output similar to:

=> IPv4 unset, auto detecting
=> IPv6 unset, auto detecting
=> StableEndpoints: ["203.0.113.10/9993"]
=> Generating ZeroTier identity
=> Generating Moon configuration
Starting Control Plane...
Starting V6 Control Plane...
Moon ID: xxxxxxxxxx
Orbit command: zerotier-cli orbit xxxxxxxxxx xxxxxxxxxx

Use the displayed command on each ZeroTier node that should orbit the Moon:

zerotier-cli orbit YOUR_MOON_ID YOUR_MOON_ID

⁠Image Tags

• latest - latest supported ZeroTierOne release
• 1.x.x - immutable versioned releases matching upstream ZeroTierOne

Example:

docker pull criogaid/zerotier-moon:1.16.2

⁠Links

• GitHub repository⁠
• GitHub Actions⁠
• ZeroTier documentation⁠