How to Install Netmaker

Purpose

How to Install and Configure Netmaker Pro On-Premise

Introduction and Documentation

Netmaker provides a flexible networking platform that can be deployed as a managed SaaS solution or self-hosted on-premise. This guide focuses on the self-hosted on-premise deployment, specifically for the Netmaker Professional version, which utilizes an automated installation script for streamlined setup.

Official Resources and Documentation

Before beginning the installation, it is essential to familiarize yourself with the official resources provided by the Netmaker team. These resources contain the most up-to-date requirements and configuration options.

• Navigate to the official Netmaker GitHub repository at github.com/gravitl/netmaker or visit the primary documentation site at learn.netmaker.io to review the initial installation requirements and architecture overview.

• Open the Quick Install guide within the documentation to access the automated setup steps and verify infrastructure compatibility.

Retrieving Professional License Credentials

If you are deploying Netmaker Professional on-premise, you must retrieve your unique licensing credentials before proceeding with the installation script. These credentials authenticate your instance with the Netmaker license server.

1. Log in to the Netmaker Account Manager portal at account.netmaker.io.

2. Identify your target tenant from the Tenants list and click the corresponding Manage button.

3. Within the Tenant Details section, navigate to the Settings tab to locate the License Key and Tenant ID fields. Copy these values, as they will be required during the command-line installation phase to enable Pro features.

Prerequisites and Server Requirements

Before initiating the installation process, it is essential to prepare a suitable environment that meets Netmaker's infrastructure and networking standards. This section outlines the necessary hardware, operating system, and firewall configurations required for a successful deployment.

Infrastructure and Hardware Specifications

Netmaker requires a clean server environment, preferably a cloud-hosted Virtual Machine (VM) with a dedicated public static IP address. While most Linux distributions are compatible, Ubuntu 24.04 is the recommended operating system for the most stable experience. The system must meet the following resource benchmarks:

• Minimum: 1 GB RAM, 1 CPU, and 2 GB of storage.

• Recommended (Production): 2 GB RAM, 2 CPUs, and 10 GB of storage.

Network and Firewall Configuration

Proper network accessibility is vital for the coordination between the Netmaker server and its clients. You must configure your cloud provider's firewall or security groups to allow traffic through several specific ports. These rules ensure that core services like the Caddy web server, CoreDNS, and the MQTT broker can communicate effectively.

Required Inbound Rules

• SSH (Port 22 TCP): For remote server management and installation.

• Web Traffic (Ports 80 & 443 TCP): Essential for Caddy to manage HTTP/HTTPS traffic and dashboard access.

• DNS (Port 53 TCP/UDP): Required for CoreDNS to resolve internal network names.

• WireGuard (Port 443 UDP): This is the default port for WireGuard traffic; ensure UDP is specifically enabled.

• WireGuard Backup (Port 51821 TCP/UDP): Highly recommended as a secondary path to ensure connectivity under restrictive network conditions.

Professional Credentials

If you are deploying the Netmaker Professional version, you must retrieve your tenant credentials before running the installation script. Log in to the Netmaker Account Manager at account.netmaker.io and navigate to the Tenant Details section. Securely copy both the License Key and the Tenant ID, as these will be requested by the automated script during the setup phase.

DNS and Firewall Configuration

Proper networking is the foundation of a successful Netmaker installation. Before proceeding with the automated script, you must configure your infrastructure to handle incoming traffic for both the management interface and the underlying WireGuard tunnels.

Inbound Firewall Rules

Access your cloud provider's firewall management console (such as DigitalOcean) and verify that the following ports are open for inbound traffic:

• Web and Certificates: TCP 80 and TCP 443 for HTTP/HTTPS and SSL certificate issuance.

• DNS: Both TCP 53 and UDP 53 to support CoreDNS functionality.

• WireGuard Connectivity: UDP 443 and UDP 51821. Note that while TCP 443 is used for the web, UDP 443 is the default port for WireGuard traffic in Netmaker.

• Redundancy: TCP 51821 as a backup for WireGuard traffic.

Security Note: Ensure SSH (TCP 22) remains open for your administrative access throughout the installation process.

Setting Up Wildcard DNS

Netmaker requires multiple subdomains for various services, including the API, dashboard, and broker. The most efficient way to manage this is by creating a wildcard A record in your DNS settings.

To configure your DNS:

1. Navigate to the DNS management page for your domain.

2. Create a new A Record.

3. In the HOSTNAME field, enter a wildcard subdomain (e.g., *.demo).

4. In the WILL DIRECT TO field, select or enter the static IP address of your target server.

By using a wildcard such as *.demo.example.com, the system will automatically resolve required addresses like api.demo.example.com and dashboard.demo.example.com without requiring additional manual DNS entries during the installation script execution.

Executing the Installation Script

Once your server prerequisites and DNS records are in place, the installation is handled by an automated script. This script orchestrates the deployment of Docker containers and configures the core Netmaker services.

Running the Setup Command

Access your server via SSH and execute the following command to download and run the Netmaker quick-install script. Note the use of the -p flag, which specifies a Professional installation:

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

Configuring the Custom Domain

The script will prompt you to select a domain type. While an auto-generated domain is available, using your own custom domain is highly recommended to avoid potential availability or crowding issues with the default server. Select option '2' for a custom domain.

When prompted, enter your base domain (e.g., demo.netmaker.io). The script will automatically generate the necessary subdomains for the API, dashboard, and broker. Review the list of subdomains and type 'y' to confirm they match your DNS wildcard configuration.

Entering Professional Credentials

Because this is a Professional installation, you must provide your license details. Return to the Netmaker Account Manager to retrieve your credentials from the Tenant Details section.

• Registration Email: Enter the email address associated with your domain registration for SSL certificate generation.

• License Key: Copy and paste your unique Pro license key.

• Tenant ID: Copy and paste your specific tenant ID.

Finalizing Installation

After entering your credentials, the script displays a SETUP ARGUMENTS summary. Verify that all values, including the domain and license information, are correct. Type 'y' to initiate the container deployment.

The script will begin pulling Docker images and starting services. This process typically takes 5 to 10 minutes depending on your server's performance and network speed. Monitor the terminal output for progress as the system creates the Netmaker networks and containers.

Dashboard Setup and Admin User

After the automated installation script concludes, the terminal will display the specific URL for your Netmaker dashboard. It is important to wait until the process is fully complete, which typically takes between 5 and 10 minutes depending on your server resources.

Initial Admin Registration

Open the provided dashboard link in your web browser. You will be directed to the Sign Up page to establish the primary administrator account. Enter a username, such as admin, and provide a secure password in the required fields. Click the Sign up button at the bottom of the form to create your credentials and initialize the system.

Security Notifications and Dashboard Access

Following the sign-up process, Netmaker offers an optional prompt to register for important security updates and version notifications. You may choose to provide your contact information for these notices or skip this step to proceed directly to the interface.

Upon completion, you will be redirected to the main Netmaker Pro dashboard. Verify that the Welcome, admin! header is visible and that the navigation sidebar contains the Networks, Devices, and Users tabs, indicating a successful installation and login.

Advanced Settings and Conclusion

Once the Netmaker Pro dashboard is operational and the initial administrative account is created, you can access advanced configuration options to harden security and integrate the server into your existing infrastructure.

Configuring Security and Identity Providers

To begin customizing your server, navigate to the Settings icon located at the bottom of the left sidebar. Within this menu, select the Security & Authentication tab to manage how users access the platform.

Under this section, you can configure Identity Providers Integration by connecting services such as Google, Microsoft Entra ID (formerly Azure AD), or GitHub. This allows for OAuth and IDP synchronization, which is essential for enterprise deployments. Additionally, you can manage more granular security parameters, such as:

• Toggling Basic Authentication on or off.

• Defining Allowed Email Domains to restrict access to specific organizations.

• Enforcing Multi-factor Authentication (MFA) for all users.

Monitoring and Server Diagnostics

For ongoing maintenance, navigate to the Monitoring & Debugging tab. Here, administrators can adjust the Verbosity Level of server logs to troubleshoot connectivity issues, toggle Telemetry data sharing, and verify the Metrics Port (defaulting to 51821) for integration with external monitoring tools.

System Notifications and Conclusion

Finally, set up the Email Configuration tab to enable system-generated notifications. You will need to provide your SMTP details, including the Host, Port, Sender Address, and Sender Username. These settings ensure that administrative alerts and security notices are delivered successfully.

With these settings configured, your Netmaker Pro installation is complete. For more complex deployment scenarios or deep-dives into specific server-side parameters, consult the advanced server installation documentation available at docs.netmaker.io.