# Platform Installation

Fast and Easy Setup for Secure Network Management

{% embed url="<https://www.youtube.com/watch?v=BpU5mMsek00>" %}

## Netmaker Platform Quick Install Guide

This guide will help you set up your Netmaker server quickly using a virtual machine, physical server, or cloud. It covers prerequisites, installation, and firewall configuration. By the end, you'll have an operational Netmaker server using WireGuard.

As an alternative, and if you're just trying out Netmaker, you can sign up at app.netmaker.io for a free 7 Day trial of our cloud version, and skip this part.

You can also sign up at app.netmaker.io to get a free PRO license to use with your server, so you can try out our professional version instead of Community.

## Prerequisites

### Operating System & Server Requirements

All components of Netmaker can run on a single server (VM or bare metal). Specifications:

* Ubuntu 24.04.
* Public static IP address (required for communication between nodes).
* Domain name (preferred) (e.g., <http://netmaker.example.com/>) with DNS management access.
* System resources:
  * Minimum: 1 GB RAM, 1 CPU, 2 GB storage.
  * Recommended (production): 2 GB RAM, 2 CPU, 10 GB storage.
* Recommendation: Use Netmaker in a dedicated network for optimal performance.

### Recommended Cloud Providers

* <https://www.digitalocean.com/> (preferred)
* <https://www.linode.com/>
* <https://aws.amazon.com/>, <https://azure.microsoft.com/>, <https://cloud.google.com/>

Note: Avoid using Oracle Cloud due to known issues with network configuration.

### Netmaker Firewall Rules

Ensure firewall settings are configured on the VM and cloud security groups (e.g., AWS, GCP) or on your router/firewall appliance to allow inbound and outbound for the following:

* 80 (For Caddy Certificate requests)
* 443 (TCP AND UDP): For the UI, REST API, MQTT broker, and WireGuard

Firewall commands:

{% code title="UFW rules" %}

```bash
# Allow HTTPS traffic for secure web connections (Caddy, Dashboard, REST API)
sudo ufw allow 443/tcp

# Allow WireGuard VPN traffic on UDP port 443 for secure peer communication
sudo ufw allow 443/udp

# Allow HTTP traffic for Caddy, which uses port 80 to generate SSL/TLS certificates automatically
sudo ufw allow 80/tcp
```

{% endcode %}

Make sure the server isn’t blocking traffic forwarding. To guarantee forwarding of traffic:

{% code title="Accept forwarding policy (iptables)" %}

```bash
iptables --policy FORWARD ACCEPT
```

{% endcode %}

For advanced debugging, view firewall logs (example using UFW):

{% code title="UFW logging and filtering" %}

```bash
# set the firewall to log only the blocked traffic
ufw logging low

# clear out the current logs
cat /dev/null | sudo tee /var/log/ufw.log

# reload ufw
ufw reload

# filter the logs
cat /var/log/ufw.log | grep -e <netmaker server IP> -e <other nodes' IPs>
```

{% endcode %}

### Domain

Your server hosts several services (netmaker server, UI, etc.) — each needs a dedicated, public subdomain. Recommendations:

* Use a publicly owned domain (e.g., <http://example.com/>, <http://mysite.biz/>)
* Designate a subdomain (e.g., \*.netmaker.example.com) for Netmaker’s services (e.g., dashboard.netmaker.example.com, api.netmaker.example.com)
* If you don’t want to use a wildcard domain (\*.netmaker.example.com): create individual DNS records (A for IPv4 and/or AAAA for IPv6) for each required subdomain:

| Purpose           | Required Subdomain              |
| ----------------- | ------------------------------- |
| Netmaker API      | `api.example.com`               |
| Dashboard UI      | `dashboard.example.com`         |
| MQTT Broker       | `broker.example.com`            |
| Prometheus        | `prometheus.example.com`        |
| Grafana           | `grafana.example.com`           |
| Netmaker Exporter | `netmaker-exporter.example.com` |

Make sure you have permission and access to modify DNS records (e.g., Route53).

{% hint style="warning" %}
Important Note on Cloudflare: Cloudflare’s proxying can interfere with MQTT functionality. You can disable proxying in the Cloudflare DNS dashboard. Cloudflare proxy configuration may lead to issues with Netmaker; Netmaker does not provide guidance for resolving these problems.
{% endhint %}

## Quick Install Script

Execute the nm-quick script for a self-hosted/on-premises setup.

To install Community Edition:

{% code title="Install Community Edition" %}

```bash
sudo wget -qO /root/nm-quick.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh
```

{% endcode %}

To install Pro Edition:

{% code title="Install Pro Edition" %}

```bash
sudo wget -qO /root/nm-quick.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh -p
```

{% endcode %}

{% hint style="warning" %}
IMPORTANT: The auto-generated domain used by the installer has been rate-limited by the certificate provider. Strongly recommend using your own domain. Using the auto-generated domain may lead to failed installation due to rate limiting.
{% endhint %}

## Integrating IdP (Pro Only)

Users can join a Netmaker server via OAuth by clicking "Login with SSO" on the dashboard login page. See the integrating IdP docs: <https://docs.netmaker.io/docs/how-to-guides/identity-provider-integration-guide>

## After the trial period ends (Pro Only)

{% stepper %}
{% step %}

### If you wish to continue using PRO

* Check these steps to obtain a pro license: <https://docs.netmaker.io/docs/server-installation/netmaker-professional-setup>
* Run:

  ```
  /root/nm-quick.sh -u
  ```

{% endstep %}

{% step %}

### If you wish to downgrade to the community version

* Run:

  ```
  /root/nm-quick.sh -d
  ```

{% endstep %}
{% endstepper %}

To get started the easiest way, visit our SaaS platform to set up a Netmaker server with a few clicks: <https://app.netmaker.io>

## Post-Installation: Accessing the Dashboard & Creating a Super Admin

Follow these steps after a successful Quick Install to create a Super Admin and verify access.

{% stepper %}
{% step %}

### Access the Netmaker Dashboard

* Open a web browser and navigate to your Netmaker dashboard URL:
  * Custom domain: `https://dashboard.example.com`
  * Auto-generated domain: `https://dashboard.nm.<your-server-ip>.nip.io` (format provided during installation)
    {% endstep %}

{% step %}

### Log In

* On the login screen, use the initial admin credentials created during installation.
  {% endstep %}

{% step %}

### Create a user

* Navigate to User Management in the left-hand sidebar.
* Click Add a User. In Netmaker Professional there are two ways to add users:
  * Basic Auth: create users with username, password, and assign groups/roles.
  * User Invite: send invitations via email (SMTP setup required for self-hosted — <https://docs.netmaker.io/docs/server-installation/advanced-options#setting-a-netmaker-server-up-for-emailing>). Invitees receive a link to create their account with pre-assigned roles/groups.

If you selected Create a User:

* Fill in Username, Password.
* Platform Access Level: select Admin.
* Click Create User.

If you selected Invite a User:

* Fill in Email address(es).
* Platform Access Level: select Admin.
* Click Create User Invite(s).
  {% endstep %}

{% step %}

### Test the Super Admin Access

* Log out of the current session.
* Log in using the new Super Admin credentials.
* Verify access to all administrative features in the dashboard.
  {% endstep %}
  {% endstepper %}

##