How to Install and Configure Netmaker on a VPS

Most infrastructure grows sideways rather than upward. A database ends up with one provider, the application layer with another, a NAS sits in the office, and half the team works from home. At some point all of it needs to reach all of it, privately.

The obvious first move is plain WireGuard with hand-written peer configs. That holds up until roughly the fifth machine. After that, every new server means editing configuration files on every existing node, and one typo silently drops part of the network.

Netmaker removes that manual step. This guide covers server and DNS preparation, a single-command install, network creation, enrollment keys, and node onboarding on Linux, Windows, macOS and Docker, plus what the free edition includes and a troubleshooting table for when something breaks.

One boundary up front. If the goal is a single VPN server with a handful of clients, plain WireGuard is enough, and the Serverspace knowledge base already covers that setup. This article is about the next tier: a managed network of dozens of machines that reach each other directly.

What Netmaker Is and Which Problem It Solves

Netmaker is an open-source automation layer for WireGuard. Its role is easiest to describe by what WireGuard leaves out: the protocol gives you fast encrypted tunnels between pairs of devices, but it does not assign addresses, distribute peer lists, or notice when a machine’s public IP changes. An administrator normally handles all of that by hand. Netmaker takes over that layer and adds:

• a web dashboard where networks are created with a button and machines join with a key;
• automatic configuration distribution, so a change on one node propagates to the rest;
• access control lists that determine which nodes may talk to which;
• a managed DNS service, so machines get readable names instead of raw private addresses;
• gateways for reaching entire subnets and onboarding remote users.

The gravitl/netmaker repository has roughly 11.6k stars and more than 640 forks, with the 1.5 branch released at the end of March 2026. The platform ships in four editions: the free self-hosted Community edition plus Teams, Business and Enterprise.

Mesh Networking Without the Jargon

Think about a home network behind a router. The laptop, the phone and the printer all get private addresses and talk directly. That is a full mesh: every device is reachable from every other. The opposite arrangement is hub-and-spoke, where all traffic passes through a central server, so the laptop’s packets travel there first and only then reach the printer.

In practice you land in between: servers mesh directly, while remote employees come in through a designated gateway. Netmaker supports both. The benefit of direct paths is twofold, lower latency and no single box carrying all traffic.

How Netmaker Compares to Managed Mesh Services

Many readers arrive here after evaluating Tailscale, ZeroTier or NetBird. Those services run the coordination plane for you: install a client, sign in, and the network exists. For a small team with no infrastructure appetite that convenience is often the right call.

Netmaker’s self-hosted model trades convenience for control. The coordination server, broker and database run on hardware you rent or own, so no third party holds key material and no external outage takes your control plane down. For organisations that must document where infrastructure data lives, whether for GDPR or a customer security questionnaire, that outweighs the setup time. Pricing differs too: managed services charge per device, while a self-hosted control plane costs whatever the server costs regardless of fleet size.

The Moving Parts: Server, Broker and Agent

The Netmaker server is a Go binary, normally run as a Docker container. It serves the dashboard API and holds configuration state: networks, nodes, users and keys.

Mosquitto, the message broker, delivers changes. Agents subscribe, the server publishes, and each agent rebuilds its local WireGuard configuration. The broker has one hard requirement: it must be reachable at a public address. Keep that in mind, it explains the most common installation failures.

Netclient is the agent on every machine. It generates key pairs, works out its own address and listening port, reports to the server, pulls the peer list and configures the WireGuard interface.

Rounding out the stack: a database (SQLite by default, PostgreSQL and rqlite as options), the Caddy reverse proxy handling TLS certificates, and a React dashboard. One detail worth remembering: for every network you create, the server spins up its own internal netclient that assists with UDP hole punching. That node lives inside Docker and never touches the host’s networking stack.

Prerequisites and Preparation

Installation takes minutes. Preparation takes about half an hour, and skipping any item below reliably breaks the install script.

The server. The documentation targets Ubuntu 24.04. Minimum resources are modest: 1 GB RAM, 1 vCPU, 2 GB storage; for production, 2 GB RAM, 2 vCPU and 10 GB. Two things are non-negotiable: a public static IP address and control over firewall rules.

The official docs name specific providers, DigitalOcean and Linode among them, but the requirement reduces to those capabilities plus a clean Ubuntu image. A VPS with a ready Ubuntu template covers this stage in a few minutes, with a dedicated address assigned at creation time.

Domain and DNS records. The simplest route is a single wildcard record, *.netmaker.example.com, pointing at the server IP. If policy forbids wildcards, create individual A records for six hostnames: api, dashboard, broker, prometheus, grafana and netmaker-exporter.

About the auto-generated domain. The installer can assemble a hostname such as nm.<your-ip>.nip.io with no DNS work. The maintainers warn against relying on it: heavy usage pushed that domain into the certificate authority’s rate limit, so installs may simply fail.

About Cloudflare. If Cloudflare serves your DNS, turn proxying off on the Netmaker records. It interferes with MQTT, producing a confusing result: the dashboard loads normally while nodes stop receiving updates.

Which Ports to Open, and What Breaks Without Them

Firewall rules usually live in two places: on the machine itself and in the provider’s security group, where one is offered. Forgetting the second layer produces the frustrating case where ufw status shows a rule and traffic still does not arrive.

The ufw commands are straightforward:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51821/udp
sudo ufw allow 443/udp

Check separately that the machine is not dropping forwarded packets. Some providers set the default policy to DROP, which quietly disables gateway features:

iptables --policy FORWARD ACCEPT

Installing Netmaker on Your VPS

With the server provisioned, DNS pointing at it and ports open, installation is a single script.

Step 1. Connect and update.

sudo apt update && sudo apt upgrade -y

Step 2. Install Docker. The platform runs in containers, and a clean Ubuntu image usually ships without the engine:

sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker

Step 3. Verify DNS. Confirm the records resolve to the right address:

dig +short dashboard.netmaker.example.com

An empty result or the wrong address means it is too early to run the installer.

Step 4. Run the installer. For the Community edition:

sudo wget -qO /root/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh

The commercial edition with a trial period uses the same script with a -p flag.

Step 5. Answer the prompts. The script asks for your domain and an email address for certificates, then handles the rest: pulling images, starting the server, dashboard, broker and proxy containers, issuing certificates and generating admin credentials. The final output holds the dashboard URL and an initial password. Save it immediately, it is not shown again.

First Login and Creating an Administrator

Open the dashboard at https://dashboard.netmaker.example.com, or at the form if you went the auto-generated route.

1. Sign in with the credentials printed by the installer.
2. Open user management from the left sidebar.
3. Create a permanent administrator with a username, password and the Admin access level.
4. Log out and log back in as the new user.
5. Confirm every administrative section is reachable.

That last step catches the case where the role was assigned incorrectly and part of the dashboard silently stays locked. Multi-factor authentication lives in platform settings and works in the free edition too.

Creating a Network and Choosing an Address Range

Netmaker provisions one network by default and you can use it as-is. For custom addressing or isolated segments, create your own from the dashboard.

The decision that matters is the private address range. It must not overlap with any network your machines connect from. The classic mistake: an administrator picks the familiar 192.168.1.0/24, and half the staff have exactly that range on their home routers. Routes collide, the tunnel appears established, nothing works. For networks under 254 machines the documentation suggests 10.11.12.0/24, 10.20.30.0/24 or 10.99.98.0/24.

Three form fields deserve a note:

• IPv4 assigns fourth-version private addresses, the standard mode;
• IPv6 layers sixth-version addressing on top of IPv4; IPv6-only is not supported;
• Default Access Control decides whether a new node may immediately reach the others.

Once the network exists, the server adds itself as a service node. Seeing it listed confirms the deployment came up correctly.

Enrollment Keys and Registration Tokens

A machine needs credentials before it can join, and Netmaker offers two forms that are easy to confuse.

An enrollment key is the secret string authorising a node to register. Keys can be unlimited, capped at a number of uses, or time-bound, and may target one network, several, or none, in which case the network is chosen later from the dashboard.

A registration token is a base64 string already containing the server address, the port and the key. Tokens are the more practical thing to distribute, since whoever runs the command need not know where the server lives.

Issue a separate key per scenario: unlimited for your own fleet, single-use and time-limited for a contractor. Exhausted and expired keys are flagged as invalid in the dashboard.

Onboarding Nodes with Netclient

The agent goes on every machine that joins. Linux prerequisites are the same everywhere: WireGuard and systemd installed.

Debian and Ubuntu. Add the project repository and install the package:

curl -sL ' | sudo gpg --dearmor -o /usr/share/keyrings/netmaker-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/netmaker-keyring.gpg] stable main" | sudo tee /etc/apt/sources.list.d/netclient.list
sudo apt update
sudo apt install netclient

RHEL, Rocky, AlmaLinux and Fedora use the rpm repository:

curl -sL ' | sudo tee /tmp/gpg.key
curl -sL ' | sudo tee /etc/yum.repos.d/netclient.repo
sudo rpm --import /tmp/gpg.key
sudo dnf install netclient

Arch and derivatives pull it from the AUR with yay -S netclient. Windows has a bundled installer, netclientbundle.exe, which accepts a quiet parameter for unattended deployment. macOS offers Homebrew via brew tap gravitl/netclient or separate packages for Apple silicon and Intel.

Docker. When installing into the host is undesirable, run the agent as a container. Host networking and privileged mode are both required:

docker run -d --network host --privileged --restart=always \
-e TOKEN=<your-token> \
-v /etc/netclient:/etc/netclient \
--name netclient gravitl/netclient:latest

A containerised agent acting as a gateway also needs these rules on the host:

iptables -I DOCKER-USER -i netmaker -j ACCEPT
iptables -I DOCKER-USER -o netmaker -j ACCEPT

Joining the network. Installing the agent joins nothing by itself. Add the machine with its token:

sudo netclient join -t <your-token>

Verifying the result. The node should appear in the dashboard member list. On the machine, sudo wg show displays tunnel state, and a ping to a neighbour’s private address confirms connectivity. Allow roughly thirty seconds for a configuration to propagate.

Virtual machines follow the same procedure as physical ones. Spinning up several VPS instances across locations and meshing them into one network is an evening’s work.

What the Free Edition Includes

Community, the free self-hosted edition: dashboard, overlay networks, the netclient agent, access control lists, enrollment keys, basic egress and gateways, managed DNS, multi-factor authentication and basic user management. That set runs a genuinely useful production network.

Teams and above add groups and roles, OAuth sign-in through an external identity provider, and the desktop and mobile end-user apps. Business brings audit logs, highly available egress and analytics. Enterprise holds white labelling, network access logs and device posture checks.

Mobile devices deserve a note, because expectations often miss here. Full meshing of phones is not part of the free edition. The documented workaround: designate a node as a remote access gateway, generate a standard WireGuard configuration for the phone, and import it via QR code.

Five Deployment Patterns Worth the Setup

1. Servers spread across providers. Database in one data centre, application in another, backups in a third. Every machine gets a private address inside one network, and only the application’s web port stays publicly exposed. The pattern fits when part of the estate runs on cloud servers and part on owned hardware.
2. Team access to internal environments. Admin panels and staging deployments never need a public route. One node becomes a remote access gateway, and access control lists determine who reaches what. Offboarding is a revocation in the dashboard rather than a firewall change.
3. Office to cloud connectivity. An egress gateway inside the office network exposes the entire local subnet, so printers, cameras and workstations need no agent.
4. Kubernetes clusters across clouds. Nodes in incompatible address spaces get a flat network and direct reachability, removing a whole category of multi-cloud routing problems.
5. Edge and IoT hardware. The agent installs on OpenWRT routers and industrial gateways; anything that cannot run it gets a plain WireGuard configuration.

Common Setup Mistakes and How to Fix Them

The same problems recur across installations. The table below maps the symptom you observe to its cause and the action that resolves it.

Two issues resist tabulation. The first is installing on an older release: the documentation targets Ubuntu 24.04, and dependency mismatches appear on 20.04 and 22.04. The second is provider choice made without reading the guidance, since Netmaker’s documentation explicitly advises against Oracle Cloud because of known networking quirks.

Limitations to Weigh Before Committing

A public address is mandatory. The message broker must be reachable from outside, so running the server behind a home router without a routable IP is not workable.

Subdomain footprint. The platform occupies three service hostnames plus the base one, which administrators comparing alternatives frequently cite against it.

You own the operations. Self-hosting means handling database backups, certificate renewal edge cases and upgrades. Servers update by changing the image tag and restarting; agents from version 0.20.5 update themselves. None of it is difficult, but it is work a managed service would absorb.

Summary and Next Steps

Deploying Netmaker follows a predictable sequence: provision a server with a static public address and a current Ubuntu image, create the subdomains, open four ports and permit packet forwarding, run the installer, create an administrator, define a network with a non-overlapping range, and distribute keys to nodes. Almost every avoidable failure happens during preparation rather than installation.

From there the network grows naturally: tighten access control lists, add an egress gateway into an office subnet, enable managed DNS, and revisit the paid editions if external authentication becomes a requirement. Starting with a two or three node test network takes about an hour and shows real behaviour under real traffic.

FAQ