Quick Install

Important Notes

  1. WE RECOMMEND USING THE NM-QUICK SCRIPT INSTEAD OF THIS GUIDE. Our docker-compose files have changed sizeably and the install script now uses a different process to obtain certificates. The script can be found on GitHub (raw script here ). If you would like to install netmaker manually, You can use the instructions below.

  2. Due to the high volume of installations, the auto-generated domain has been rate-limited by the certificate provider. For this reason, we strongly recommend using your own domain. Using the auto-generated domain may lead to a failed installation due to rate limiting.

  3. This guide is just a manual version of the steps perfomed by that script, and is therefore more prone to error.

  4. You must decide if you are installing the EE version of Netmaker or the Community version. We reccommend EE because of its substantial free tier, but it does require an account.

  5. If deploying to DigitalOcean, you should use the DigitalOcean 1-Click, which uses the interactive script.

  6. This instance will not be HA. However, it should comfortably handle 100+ concurrent clients and support the most common use cases.

  7. For information about deploying more advanced configurations, see the Advanced Installation docs.

0. Prerequisites

  • Virtual Machine

    • Preferably from a cloud provider (e.x: DigitalOcean, Linode, AWS, GCP, etc.)

    • We highly recommend that Netmaker be deployed in a dedicated networking environment. It should not share a local network with the clients which it will be managing. This can cause routing issues.

    • We do not recommend Oracle Cloud, as VM’s here have been known to cause network interference.

    • The machine should have a public, static IP address

    • The machine should have at least 1GB RAM and 1 CPU (2GB RAM preferred for production installs)

    • 2GB+ of storage

    • Ubuntu 21.04 Installed

  • Domain

    • A publicly owned domain (e.x. example.com, mysite.biz)

    • Permission and access to modify DNS records via DNS service (e.x: Route53)

    • Note on Cloudflare: Many of our users use Cloudflare for DNS. Cloudflare has limitations on subdomains you must be aware of, which can cause issues once Netmaker is deployed. Cloudflare will also proxy connections, which MQ does not like. This can be disabled in the Cloudflare dashboard. If setting up your Netmaker server using Cloudflare for DNS, be aware that the configuration of Cloudflare may cause problems with Netmaker which must be resolved, and at this point, Netmaker is not providing guidance on this setup.

1. Prepare DNS

Create a wildcard A record pointing to the public IP of your VM. As an example, *.netmaker.example.com. Alternatively, create records for these specific subdomains:

  • dashboard.domain

  • api.domain

  • broker.domain

  • stun.domain

  • turn.domain

  • turnapi.domain

If deploying EE, you will also need records for the following:

  • grafana.domain

  • prometheus.domain

  • netmaker-exporter.domain

2. Install Dependencies

ssh root@your-host
sudo apt-get update
sudo apt-get install -y docker.io docker-compose wireguard

At this point you should have all the system dependencies you need.

3. Open Firewall

Make sure firewall settings are set for Netmaker both on the VM and with your cloud security groups (AWS, GCP, etc).

Make sure the following ports are open both on the VM and in the cloud security groups:

  • 443, 80 (tcp): for Caddy, which proxies the Dashboard (UI), REST API (Netmaker Server), and Broker (MQTT)

  • 3478 (STUN): Port 3478 is reserved for UDP traffic related to STUN. By using the standard port 3478, STUN servers can work effectively with most firewall and NAT configurations, as they typically allow traffic on well-known ports.

  • 3479, 8089 (TURN, TURN api): Port 3479 is commonly used for UDP traffic related to TURN. Similar to STUN, TURN servers need to work effectively with firewalls and NAT devices. By using the reserved port 3479, TURN servers can better handle communication across various network configurations. Port 8089 is not reserved specifically for TURN but is commonly associated with TURN server deployments.

  • 51821-518XX (udp): for WireGuard - Netmaker needs one port per network, starting with 51821, so open up a range depending on the number of networks you plan on having. For instance, 51821-51830.

  • 8085 (exporter EE): If you are building an EE server, you need this port open.

  • 1883, 8883 8083, 18083 (if using EMQX): We use two different types of brokers. There is Mosquitto or EMQX. if you are setting up EMQX, these four need to be open for MQTT, SSL MQTT, web sockets, and the EMQX dashbaord/REST api.

sudo ufw allow proto tcp from any to any port 443
sudo ufw allow proto tcp from any to any port 80
sudo ufw allow proto tcp from any to any port 3478
sudo ufw allow proto tcp from any to any port 3479
sudo ufw allow proto tcp from any to any port 8089
sudo ufw allow 51821:51830/udp

It is also important to make sure the server does not block forwarding traffic (it will do this by default on some providers). To ensure traffic will be forwarded:

iptables --policy FORWARD ACCEPT
Again, based on your cloud provider, you may additionally need to set inbound security rules for your server (for instance, on AWS). This will be dependent on your cloud provider. Be sure to check before moving on:

  • allow 443/tcp from all

  • allow 80/tcp from all

  • allow 3478/tcp from all

  • allow 3479/tcp from all

  • allow 8089/tcp from all

  • allow 51821-51830/udp from all

4. Prepare MQ

You must retrieve the MQ configuration file for Mosquitto and the wait script.

wget -O /root/mosquitto.conf https://raw.githubusercontent.com/gravitl/netmaker/master/docker/mosquitto.conf
wget -q -O /root/wait.sh https://raw.githubusercontent.com/gravitl/netmaker/master/docker/wait.sh
chmod +x wait.sh

5. Install Netmaker

Prepare Docker Compose

As of 0.20.0, our docker-compose and Caddyfile now contains references to a netmaker.env file. This will cut down on repetitive entries like inserting your base domain multiple times. You only insert it once in your netmaker.env file and the backend handles placing it in the right places. The EMQX and EE docker-composes are now extensions of the regular docker-compose file, so switching to EE or EMQX doesn’t involve recreating an entire docker-compose file.

Get the base docker-compose and Caddyfile.

wget https://raw.githubusercontent.com/gravitl/netmaker/master/compose/docker-compose.yml
wget https://raw.githubusercontent.com/gravitl/netmaker/master/docker/Caddyfile

If you plan on using an Enterprise server (EE), then you will need to grab the Caddyfile-EE file instead. There will be more EE related instructions below in “Extra Steps for EE”.

wget https://raw.githubusercontent.com/gravitl/netmaker/master/docker/Caddyfile-EE

You can grab the netmaker.env file here.

wget https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/netmaker.default.env
cp netmaker.default.env netmaker.env

You can then use a text editor like vim or nano to go in there and fill out the fields. There is an example below to reference. You can get your ip with the command ip route get 1 | sed -n 's/^.*src \([0-9.]*\) .*$/\1/p'. You can also generate random strings for the master key and TURN and MQ passwords with the command tr -dc A-Za-z0-9 </dev/urandom | head -c 30 ; echo '' or you can enter them manually if desired. For the base domain again, we advise you use your own domain, because nip.io can hit rate limiting easily from the high volume when obtaining certificates. If you do want to use nip.io, just enter nm.<YOUR_IP_WITH_DASHES_INSTEAD_OF_DOTS>.nip.io.

# Email used for SSL certificates
NM_EMAIL=example@email.com
# The base domain of netmaker
NM_DOMAIN=nm.123-456-789-012.nip.io
# Public IP of machine
SERVER_HOST=<YOUR_IP_ADDRESS>
# The admin master key for accessing the API. Change this in any production installation.
MASTER_KEY=<RANDOM_STRING>
# The username to set for turn api access
TURN_USERNAME=<EXAMPLE_USERNAME>
# The password to set for turn api access
TURN_PASSWORD=<EXAMPLE_PASSWORD>
# The username to set for MQ access
MQ_USERNAME=<EXAMPLE_USERNAME>
# The password to set for MQ access
MQ_PASSWORD=<EXAMPLE_PASSWORD>
# Specify the type of server to install. Use ee for enterprise and ce for community edition
INSTALL_TYPE=ce
# The next two are for Enterprise edition. You can find that info below on "Extra steps for EE"
NETMAKER_ACCOUNT_ID= (for EE version)
LICENSE_KEY= (for EE version)
# The version for the netmaker and netmaker-ui servers. current version is v0.20.2.
# Some versions of docker may try to include quotation marks in this reference, so don't put them in.
SERVER_IMAGE_TAG=v0.20.2
UI_IMAGE_TAG=v0.20.2
# used for HA - identifies this server vs other servers
NODE_ID="netmaker-server-1"
METRICS_EXPORTER="off" (turn on for EE)
PROMETHEUS="off"  (turn on for EE)
# Enables DNS Mode, meaning all nodes will set hosts file for private dns settings
DNS_MODE="on"
# Enable auto update of netclient ? ENUM:- enabled,disabled | default=enabled
NETCLIENT_AUTO_UPDATE="enabled"
# The HTTP API port for Netmaker. Used for API calls / communication from front end.
# If changed, need to change port of BACKEND_URL for netmaker-ui.
API_PORT="8081"
EXPORTER_API_PORT="8085"
# The "allowed origin" for API requests. Change to restrict where API requests can come from with comma-separated
# URLs. ex:- https://dashboard.netmaker.domain1.com,https://dashboard.netmaker.domain2.com
CORS_ALLOWED_ORIGIN="*"
# Show keys permanently in UI (until deleted) as opposed to 1-time display.
DISPLAY_KEYS="on"
# Database to use - sqlite, postgres, or rqlite
DATABASE="sqlite"
# The address of the mq server. If running from docker compose it will be "mq". Otherwise, need to input address.
# If using "host networking", it will find and detect the IP of the mq container.
SERVER_BROKER_ENDPOINT="ws://mq:1883"
# The reachable port of STUN on the server
STUN_PORT="3478"
# Logging verbosity level - 1, 2, or 3
VERBOSITY="1"
# If ON, all new clients will enable proxy by default
# If OFF, all new clients will disable proxy by default
# If AUTO, stick with the existing logic for NAT detection
DEFAULT_PROXY_MODE="off"
# Port to access turn server
TURN_PORT="3479"
# Config for using turn, accepts either true/false
USE_TURN="true"
DEBUG_MODE="off"
TURN_API_PORT="8089"
# Enables the REST backend (API running on API_PORT at SERVER_HTTP_HOST).
# Change to "off" to turn off.
REST_BACKEND="on"
# If turned "on", Server will not set Host based on remote IP check.
# This is already overridden if SERVER_HOST is set. Turned "off" by default.
DISABLE_REMOTE_IP_CHECK="off"
# Whether or not to send telemetry data to help improve Netmaker. Switch to "off" to opt out of sending telemetry.
TELEMETRY="on"
###
#
# OAuth section
#
###
# "<azure-ad|github|google|oidc>"
AUTH_PROVIDER=
# "<client id of your oauth provider>"
CLIENT_ID=
# "<client secret of your oauth provider>"
CLIENT_SECRET=
# "https://dashboard.<netmaker base domain>"
FRONTEND_URL=
# "<only for azure, you may optionally specify the tenant for the OAuth>"
AZURE_TENANT=
# https://oidc.yourprovider.com - URL of oidc provider
OIDC_ISSUER=

Extra Steps for EE (note: there is a substantial free tier for EE, so this is often worthwhile)

  1. Log into https://dashboard.license.netmaker.io”

  2. Copy License Key Value: https://dashboard.license.netmaker.io/license-keys”

  3. Retrieve Account ID: https://dashboard.license.netmaker.io/user”

  4. Place the licence key and account ID in the netmaker.env file.

  5. In the netmaker.env file, change the METRICS_EXPORTER and PROMETHEUS from off to on.

  6. Grab the docker-compose.ee extension file from the repo.

wget https://raw.githubusercontent.com/gravitl/netmaker/master/compose/docker-compose.ee.yml

You will not need to make any changes to this file. It will reference the current netmaker.env file.

6. Get Certificates

Start by grabbing our nm-certs shell script, make it executable, and run it.

wget https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-certs.sh
chmod +x nm-certs.sh
bash nm-certs.sh

If the script runs successfully, you should see a message like SSL certificates ready.

Then run

ln -fs /root/netmaker.env /root/.env

7. Start Netmaker

sudo docker-compose -f docker-compose.yml up -d --force-recreate

navigate to dashboard.<your base domain> to begin using Netmaker.

To troubleshoot issues, start with:

docker logs netmaker

Or check out the troubleshoooting docs.