xubiaolin/docker-zerotier-planet: self-hosting a ZeroTier root server in a container

The problem: ZeroTier's root servers are not yours

ZeroTier's own documentation describes PLANET nodes as the root servers that handle network discovery and the initial connection between devices. Every client ships with a planet file pointing at ZeroTier's infrastructure. The README of this project frames the motivation around that dependency: the official servers sit overseas, which it says makes access from mainland China slow and unstable, and a self-hosted root removes reliance on a third party for both latency and availability.

The audience is narrow and specific. You need a Linux machine with a public IP address, Docker, and Git. The README lists Debian 12, Ubuntu 20.04 or newer, and Rocky Linux as the recommended bases, plus AMD64 and ARM64 as the supported architectures. If you are a single user who wants a slightly faster path to a home NAS, this is more machinery than the problem deserves. If you run a fleet of devices and want the controller and the root under one operator, the trade is more even.

What the image actually builds, and why it is slow

The Dockerfile is a two-stage build on Alpine 3.14. The builder stage installs a wide toolchain (git, python3, npm, make, g++, linux-headers, curl, pkgconfig, openssl-dev, jq, build-base, gcc, cmake, go), installs Rust through rustup, clones ZeroTierOne, checks out the tag passed as the TAG build argument, and runs make ZT_SYMLINK=1 followed by make and make install. It then starts zerotier-one briefly, kills it, and moves into attic/world to compile mkworld. That last step swaps in patch/mkworld_custom.cpp in place of mkworld.cpp before running build.sh, and the resulting mkworld binary is placed in /var/lib/zerotier-one. A second build stage clones ztncui and installs its Node dependencies.

The runtime stage is a fresh Alpine 3.14 with three ports declared as environment variables: ZT_PORT=9994, API_PORT=3443 and FILE_SERVER_PORT=3000. It also defines IP_ADDR4 and IP_ADDR6, both empty, plus GH_MIRROR and FILE_KEY. Because ZeroTier One is compiled from source rather than pulled from a package, the first image build is long and depends on network access to GitHub and to the Rust installer. The README's estimate of one to three minutes refers to running the deploy script against a prebuilt image, not to building that image from scratch.

Installing it and creating your first network

The README's install path is a clone followed by an interactive script. On Debian or Ubuntu, Git and Docker come first, then the repository, then deploy.sh, which presents a numbered menu with install, uninstall, update, view information and exit options. The install writes planet and moon configuration files into ./data/zerotier/dist, and the script prints a URL from which they can be downloaded; scp is the alternative the README names.

apt update && apt install git -y
curl -fsSL https://get.docker.com | bash
service docker start
git clone https://github.com/xubiaolin/docker-zerotier-planet.git
cd docker-zerotier-planet
./deploy.sh

When the script finishes it prints a menu and, on success, an install-complete screen. The management interface is then reachable at http://ip:3443, where the README gives the default credentials as admin and password. You create a network under the Networks menu with Add Network, and the controller assigns a network ID that you will need on every client.

# after ./deploy.sh completes
ls ./data/zerotier/dist
# planet and moon files are written here

On the client side the pattern is the same everywhere: replace the planet file, restart the service, join, then authorise the device in the web controller. Windows stores it at C:\ProgramData\ZeroTier\One, Linux at /var/lib/zerotier-one, macOS at /Library/Application Support/ZeroTier/One/. The README's PowerShell example shows the expected result after joining and restarting:

PS C:\Windows\system32> zerotier-cli.bat peers
200 peers
<ztaddr>   <ver>  <role> <lat> <link> <lastTX> <lastRX> <path>
fcbaeb9b6c 1.8.7  PLANET    52 DIRECT 16       8994     1.1.1.1/9993
fe92971aad 1.8.7  LEAF      14 DIRECT -1       4150     2.2.2.2/9993

A PLANET line with a DIRECT link is the signal that the client is talking to your root rather than the default one. Android is not covered by a stock client here; the README points at the unofficial ZerotierFix app instead.

The planet file is the whole security boundary

Replacing the planet file is not a performance tweak. It redirects the client's root of trust. Any device still holding the stock planet file is on ZeroTier's network, not yours, and any device holding yours will not fall back to the public roots if your server is down. The README treats the generated files as something to store carefully and distribute to every client, and that is the operational cost of the whole design: a root server you control is also a root server you must keep reachable.

The management panel compounds this. The README's default login is admin with password, served over plain HTTP on port 3443, and there is a separate section for adding SSL to the panel. Until that is done, anyone who can reach 3443 can attempt the documented default credentials. The repository does not document a forced password change on first login, so rotating it is something you do deliberately rather than something the install does for you. Ports 9994/tcp and 9994/udp carry the ZeroTier traffic and are exposed to the internet by design; the README notes they can be adjusted to fit your environment.

Where this is the wrong tool: MOON instead of PLANET

The README distinguishes the two roles clearly. A MOON is a user-built private root that acts as a regional relay, helping nearby devices establish connections faster. A PLANET is the core root server responsible for network discovery and the initial connection. If your goal is lower latency between devices in one region, a MOON addresses it without changing what every client trusts, and without making your server a single point of failure for the entire network.

Building a PLANET is a commitment to being the authority. Every client must be reconfigured, and the alternative to this project for the controller half is ztncui or another controller front end talking to ZeroTier One directly, which is essentially what this image already packages. The difference is packaging and automation, not capability. If you want a managed path, the README itself lists a hosted container service with a three-day trial and a yearly fee, which is a candid admission that self-hosting is not the only answer.

Maintenance, licensing and the upgrade path

The last push to the repository was on 2026-08-11, and the most recent tagged release is v2.1.0 from 2024-05-19. The deploy script offers an update option, and because ZeroTier One is compiled from a tag passed as the TAG build argument, upgrading the underlying ZeroTier version means rebuilding the image rather than pulling a new base. That is the main maintenance cost: a source build tied to Alpine 3.14, which is an old base, and a build that needs GitHub and the Rust installer to be reachable.

The repository does not state a licence, and the README does not discuss licensing terms. The image compiles ZeroTierOne and clones ztncui, both of which carry their own licences that you would need to check before redistribution or commercial use. Nothing here is legal advice; the point is that the absence of a stated licence in this repository is itself a fact worth resolving before you build a product on top of it. The README also carries a risk statement section, which is a reasonable place to start reading before you point production traffic at it.

Editorial conclusion

Adopt it if you have a Linux host with a public IP and you want the ZeroTier root role under your own control, with ztncui giving you a browser controller on port 3443. Do not adopt it if you only need faster peer paths between a handful of devices, because a MOON covers that and leaves the root role alone, and do not adopt it if you cannot distribute a replaced planet file to every client. Before rollout, confirm the licence of the repository and of the two upstream projects it builds, and confirm that 3443/tcp and 9994 tcp+udp are reachable from the clients you intend to enrol.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. xubiaolin/docker-zerotier-planet on GitHub