- 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.
- 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.
- This guide is just a manual version of the steps performed by that script, and is therefore more prone to error.
- You must decide if you are installing the Pro version of Netmaker or the Community version. We recommend Pro because of its substantial free limits, but it does require an account.
- If deploying to DigitalOcean, you should use the DigitalOcean 1-Click, which uses the interactive script.
- This instance will not be HA. However, it should comfortably handle 100+ concurrent clients and support the most common use cases.
- For information about deploying more advanced configurations, see the :doc:`Advanced Installation <./server-installation>` docs.
All components of Netmaker can be run on a single server (Virtual Machine or Bare Metal). Here some recommendations for setting up the server:
- We highly recommend that Netmaker be deployed in a dedicated networking environment.
- 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
If you do not have a host for this server, here are some recommendations:
- DigitalOcean (preferred)
- Linode
- KeepSec
- AWS
- Azure
- GCP
- We do not recommend Oracle Cloud. There are known issues with their network configuration.
Your server will host several services (netmaker server, UI, etc.) each of which requires a dedicated, public subdomain. Here are some recommendations:
- Use a publicly owned domain (e.x. example.com, mysite.biz)
- Designate a subdomain (e.g. netmaker.example.com) for netmaker's services (e.g. dashboard.netmaker.example.com)
- Make sure you have permission and access to modify DNS records for your domain (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.
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
If deploying Pro, you will also need records for the following:IsStatic
- grafana.domain
- prometheus.domain
- netmaker-exporter.domain
ssh root@your-host sudo apt-get update sudo apt-get install -y docker.io docker-compose
At this point you should have all the system dependencies you need.
Please refer to the Firewall Rules for Netmaker Server for more information.
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
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 Pro docker-composes are now extensions of the regular docker-compose file, so switching to Pro 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 a Professional server (Pro), then you will need to grab the Caddyfile-pro file instead. There will be more Pro related instructions below in "Extra Steps for Pro".
wget https://raw.githubusercontent.com/gravitl/netmaker/master/docker/Caddyfile-pro
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 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 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 pro for professional and ce for community edition
INSTALL_TYPE=ce
# The next two are for Professional edition. You can find that info below on "Extra steps for Pro"
NETMAKER_TENANT_ID= (for Pro version)
LICENSE_KEY= (for Pro 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 Pro)
PROMETHEUS="off" (turn on for Pro)
# 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
# This setting is no longer available from v0.20.5
DEFAULT_PROXY_MODE="off"
DEBUG_MODE="off"
# 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=- Visit https://app.netmaker.io to create your account on the Netmaker SaaS platform.
- Create a tenant of type
On-Premto obtain a license key. more details in :doc:`Netmaker Professional setup <./pro/pro-setup>` - Retrieve Tenant ID and license key from the tenant's settings tab.
- Place the licence key and tenant ID in the netmaker.env file.
- In the netmaker.env file, change the METRICS_EXPORTER and PROMETHEUS from off to on.
- Grab the docker-compose.pro extension file from the repo and change its name to docker-compose.override.yml.
wget https://raw.githubusercontent.com/gravitl/netmaker/master/compose/docker-compose.pro.yml
You will not need to make any changes to this file. It will reference the current netmaker.env file.
Then run
ln -fs /root/netmaker.env /root/.env
Users are also allowed to join a Netmaker server via OAuth. They can do this by clicking the "Login with SSO" button on the dashboard's login page. Check out the :doc:`integrating oauth docs <./oauth>`.
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 :doc:`troubleshoooting docs <./troubleshoot>`.