ZeroUI - ZeroTier Controller Web UI - is a web user interface for a self-hosted ZeroTier network controller.
Explore the screenshots »

Bug Report · Feature Request · Ask a Question

Table of Contents

• About
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Google sign-in
  • Setting it up
  • How accounts work
  • Making Google mandatory
  • Password sign-in as a break-glass login
• Usage
  • Update
  • Backup
• Roadmap
• Contributing
  • Development environment
• Support
• Security
• Copyright notice
• License

---

About

This project drew inspiration from ztncui and was developed to address the current limitations of self-hosted network controllers. Some of the issues in ztncui cannot be resolved due to the core architecture of the project. ZeroUI aims to resolve these issues and introduces the following features:

• It is a lightweight Single Page Application (SPA) built with React, providing an improved user experience, and it is mobile-friendly.
• ZeroUI is compatible with the ZeroTier Central API, allowing you to use CLI tools and custom applications designed for ZeroTier Central to manage your networks.
• ZeroUI implements controller-specific workarounds to address certain existing issues that are not addressed in ZTNCUI.
• ZeroUI is more feature-complete, supporting almost all network controller features, including a rule editor. Development is ongoing, so you can expect regular updates with new features and bug fixes.
• Deploying ZeroUI is straightforward; refer to the installation section for more information.

Curious about ZeroTier?

ZeroTier is an impressive open-source project available on a wide range of platforms. It can resolve many of your complex networking issues, potentially replacing your intricate VPN setups. You can create a virtual LAN and manage all your devices effortlessly.

In essence, ZeroTier combines the capabilities of VPN and SD-WAN, simplifying network management.

Built With

Frontend:

• React
• Material UI

Backend:

• NodeJS
• Express
• Lowdb

Ready-to-use deployment solution:

• Docker
• Docker Compose
• Caddy

Getting Started

Prerequisites

The recommended way to install ZeroUI is by using Docker and Docker Compose. To install Docker and Docker Compose on your system, please follow the installation guide in the official Docker documentation.

For HTTPS setup, you will need a domain name. You can obtain one for free at https://www.duckdns.org.

Installation

Here's a straightforward one-minute installation guide, perfect for a fresh VPS setup:

1. Create a project directory

mkdir -p /srv/zero-ui/
cd /srv/zero-ui/

2. Download the docker-compose.yml file

wget https://raw.githubusercontent.com/dec0dOS/zero-ui/main/docker-compose.yml

or

curl -L -O https://raw.githubusercontent.com/dec0dOS/zero-ui/main/docker-compose.yml

3. Replace YOURDOMAIN.com with your domain name and set admin credentials (ZU_DEFAULT_PASSWORD) in docker-compose.yml
4. Pull the image

docker pull dec0dos/zero-ui

5. Run the containers

docker compose up -d --no-build

6. Check if everything is okay (CTRL-C to stop log preview)

docker compose logs -f

7. Disable your firewall for the following ports: 80/tcp, 443/tcp, and 9993/udp

• On Ubuntu/Debian with ufw installed:

ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 9993/udp

• Or you can use iptables:

iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT
iptables -A INPUT -p udp --dport 9993 -j ACCEPT

8. Navigate to https://YOURDOMAIN.com/app/. Now you can use your ZeroUI instance with HTTPS support and automated certificate renewal.

To disable Caddy proxy and HTTPS, remove the https-proxy from docker-compose.yml, set ZU_SECURE_HEADERS to false, and change zero-ui port expose to ports.

Advanced manual setups are also supported. Check the following environment variables as a reference:

Name	Default value	Description
NODE_ENV	unset	You could learn more here
LISTEN_ADDRESS	0.0.0.0	Express server listen address
ZU_SERVE_FRONTEND	true	You could disable frontend serving and use ZeroUI instance as REST API for your ZeroTier controller
ZU_SECURE_HEADERS	true	Enables helmet
ZU_CONTROLLER_ENDPOINT	http://localhost:9993/	ZeroTier controller API endpoint
ZU_CONTROLLER_TOKEN	from /var/lib/zerotier-one/authtoken.secret	ZeroTier controller API token
ZU_DEFAULT_USERNAME	unset (docker-compose.yml: admin)	Default username that will be set on the first run. Optional once Google sign-in is configured
ZU_DEFAULT_PASSWORD	unset (docker-compose.yml: zero-ui)	Default password that will be set on the first run. Optional once Google sign-in is configured
ZU_GOOGLE_CLIENT_ID	unset	Google OAuth client ID. Setting this and the secret enables Google sign-in
ZU_GOOGLE_CLIENT_SECRET	unset	Google OAuth client secret
ZU_GOOGLE_ALLOWED_DOMAINS	unset	Comma-separated email domains allowed to sign in, e.g. example.com. Required when Google sign-in is enabled: an empty value rejects every sign-in rather than letting any Google account in
ZU_GOOGLE_REDIRECT_URI	derived from the request	Pin the OAuth callback URL. Set this when running behind a reverse proxy that rewrites the host
ZU_LOCAL_LOGIN	false when Google is configured, otherwise true	Whether username and password sign-in is accepted. false makes Google mandatory for everyone, which also retires the legacy per-user static token. Set to true to keep a break-glass login alongside Google
ZU_SESSION_TTL_HOURS	168	How long a session stays valid before the user has to sign in again
ZU_DATAPATH	data/db.json	ZeroUI data storage path
ZU_DISABLE_AUTH	false	If set to true, automatically log in all users. This is useful if ZeroUI is protected by an authentication proxy. Note that when this value is changed, the localStorage of instances of logged-in panels should be cleared
ZU_LAST_SEEN_FETCH	true	Enables Last Seen feature
ZU_LAST_SEEN_SCHEDULE	*/5 * * * *	Last Seen cron-like schedule
ZU_LOGIN_LIMIT	false	Enable rate limiter for /login endpoint
ZU_LOGIN_LIMIT_WINDOW	30	The duration of the IP ban in minutes
ZU_LOGIN_LIMIT_ATTEMPTS	50	Login attemps before ban

ZeroUI could be deployed as a regular nodejs web application, but it requires a ZeroTier controller that is installed with the zerotier-one package. For more info about the network controller, you could read here.

For Ansible Role, please refer to the zero-ui-ansible repository.

Controller Setup Tips (Outside Docker)

If you are using an existing controller on the host, you may need to allow connections from the Docker container. There are two ways to do this:

1. Allow controller management from any IP address:

echo "{\"settings\": {\"portMappingEnabled\": true,\"softwareUpdate\": \"disable\",\"allowManagementFrom\": [\"0.0.0.0/0\"]}}" > /var/lib/zerotier-one/local.conf

Warning: Don't forget to block connections to 9993/TCP from the WAN. Directly exposing the controller API to the WAN is not recommended; it should be proxified via the ZeroUI backend.

2. Add network_mode: "host" to zero-ui in docker-compose.yml.

For more information, please refer to this discussion.

Google sign-in

ZeroUI can sign users in with Google instead of a shared username and password, restricted to the email domains you nominate. Every user gets the same permissions -- there are no roles.

Setting it up

1. In the Google Cloud console, create an OAuth client ID of type Web application.

2. Add your ZeroUI callback to Authorized redirect URIs:

   https://YOURDOMAIN.com/auth/google/callback
   

3. Put the client ID, the secret, and your domains in the environment:

   environment:
     - ZU_GOOGLE_CLIENT_ID=xxxxxxxx.apps.googleusercontent.com
     - ZU_GOOGLE_CLIENT_SECRET=xxxxxxxx
     - ZU_GOOGLE_ALLOWED_DOMAINS=example.com

ZU_GOOGLE_ALLOWED_DOMAINS is not optional. Leaving it empty rejects every sign-in rather than quietly accepting any Google account on the internet.

Behind a reverse proxy that rewrites the host, set ZU_GOOGLE_REDIRECT_URI to the exact URI you registered above.

How accounts work

• Anyone whose Google email is on an allowed domain can sign in. Their account is created on first sign-in -- there is no invite step.
• Signing in gives every user the same permissions, including the ability to manage other users.
• Users in the menu lists everyone who has signed in. From there you can disable an account (which drops its sessions immediately and blocks future sign-ins) or delete it.
• You cannot disable or delete your own account, so an instance can't be locked out from its own UI.
• Deleting an account does not permanently ban the person: if their email is still on an allowed domain, signing in again creates a fresh account. Use disable to keep someone out, or remove them from your Google Workspace.

Making Google mandatory

ZU_LOCAL_LOGIN=false makes Google the only way in, for every user. It is also the default as soon as Google is configured, so you get this without setting anything.

That covers both ways a user could otherwise skip Google:

• the username and password form is refused, and
• the long-lived per-user token written by older versions stops being accepted.

The second one matters on an upgrade. That token predates Google sign-in and is stored in db.json, so locking only the password form would leave it as an open side door into the same shared admin account. While Google is mandatory, no local account can hold a usable session at all -- including one it was issued before you flipped the switch.

Accounts that can no longer sign in are still listed under Users, marked Cannot sign in, so you can see and delete them.

Nothing is destroyed by this: password hashes and legacy tokens stay in db.json and start working again if you set ZU_LOCAL_LOGIN=true.

If ZU_LOCAL_LOGIN=false and Google is not configured, nobody could sign in at all, so the backend refuses to start and says so rather than coming up unusable. The exception is ZU_DISABLE_AUTH=true, where a proxy in front is doing the authentication.

Password sign-in as a break-glass login

Set ZU_LOCAL_LOGIN=true to keep the password form alongside Google -- worth doing on a first rollout, in case the OAuth client is misconfigured.

Existing installations keep working across an upgrade: the ZU_DEFAULT_USERNAME account is preserved, and stays usable as long as local login is enabled.

Usage

After installation, log in with the credentials declared with ZU_DEFAULT_USERNAME and ZU_DEFAULT_PASSWORD, or with Google if you configured it (see Google sign-in).

Currently, some main ZeroTier Central features are missing. Refer to the roadmap for more information.

For screenshots, please refer to the screenshots section.

Update

To get the latest version, simply run

docker compose pull && docker compose up -d --no-build

in the folder where docker-compose.yml is located. Backups may not be necessary since most of your data is usually saved at the controller level, but it's still a good idea to consider them as a precautionary measure.

Backup

You should regularly back up the zerotier-one and data folders in your ZeroUI installation directory. You can do this manually before upgrading using the following commands:

tar cvf backup-ui.tar data/
tar cvf backup-zt.tar zerotier-one/

Roadmap

For a list of proposed features (and known issues), see the open issues.

• Top Feature Requests (Add your votes using the 👍 reaction)
• Top Bugs (Add your votes using the 👍 reaction)
• Newest Bugs

When creating bug reports, please ensure they are:

• Reproducible. Include steps to reproduce the problem.
• Specific. Provide as much detail as possible, including version, environment, etc.
• Unique. Avoid duplicating existing open issues.
• Scoped to a Single Bug. Report one bug per issue.

Contributing

Firstly, thank you for considering contributing! Contributions are what make the open-source community thrive. Any contributions you make will benefit everyone, and they are highly appreciated.

To contribute:

1. Fork the project.
2. Create your feature branch (git checkout -b feat/amazing_feature).
3. Commit your changes (git commit -m 'feat: add amazing_feature').
4. Push to the branch (git push origin feat/amazing_feature).
5. Open a Pull Request

ZeroUI uses conventional commits, so please follow the guidelines. You can use yarn commit to open a Text-Based User Interface (TUI) that follows conventional commits guidelines.

Development Environment

To set up a development environment, follow these steps:

1. Clone the repo

git clone https://github.com/dec0dOS/zero-ui.git
cd zero-ui

2. Install packages

yarn install

3. Start the development server

yarn dev

4. Navigate to http://localhost:3000

You will also need to install the ZeroTier controller. On Linux, installing the zerotier-one package is sufficient, but other platforms may require some adjustments. First, you should obtain the controller token. On macOS, you can find it using the following command:

sudo cat "/Library/Application Support/ZeroTier/One/authtoken.secret"

Afterward, you can start the ZeroUI development environment:

ZU_CONTROLLER_TOKEN=TOKEN_FROM_authtoken.secret yarn dev

For other platforms, please refer to the ZeroTier manual.

Support

If you need assistance or have questions, reach out through GitHub Discussions.

Security

ZeroUI follows best practices for security, but complete security cannot be guaranteed. ZeroUI is provided "as is" without any warranty. Use at your own risk.

For enterprise support and a more reliable and scalable solution, please consider using ZeroTier Central.

For more information and to report security issues, please refer to our security documentation.

Copyright Notice

ZeroUI is not affiliated with, associated with, or endorsed by ZeroTier Central or ZeroTier, Inc.

License

See LICENSE for more information.