=============== Quick Install =============== This quick start guide is an **opinionated** guide for getting up and running with Netmaker as quickly as possible. 0. Introduction ================== We assume for this installation that you want all of the Netmaker features enabled, want your server to be secure, and want it to be accessible from anywhere. This instance will not be HA. However, it should comfortably handle around one hundred concurrent clients and support most use cases. If you are deploying for an enterprise use case, please contact info@gravitl.com for support. By the end of this guide, you will have Netmaker installed on a public VM linked to your custom domain, secured behind an Nginx reverse proxy. If this configuration does not fit your use case, see the :doc:`Advanced Installation <./server-installation>` docs. 1. Prerequisites ================== - **Virtual Machine** - Preferably from a cloud provider (e.x: DigitalOcean, Linode, AWS, GCP, etc.) - Public, static IP - Min 2GB RAM, 1 CPU (4GB RAM, 2CPU preferred) - 5GB+ of storage - Ubuntu 20.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) 2. Install Dependencies ======================== ``ssh root@your-host`` Install Docker --------------- Begin by installing the community version of Docker and docker-compose (there are issues with the snap version). You can follow the official `Docker instructions here `_. Or, you can use the below series of commands which should work on Ubuntu 20.04. .. code-block:: sudo apt-get remove docker docker-engine docker.io containerd runc sudo apt-get update sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose docker --version docker-compose --version At this point Docker should be installed. Install Dependencies ----------------------------- In addition to Docker, this installation requires WireGuard, Nginx, and Certbot. ``sudo apt install wireguard wireguard-tools nginx certbot python3-certbot-nginx net-tools`` 3. Prepare VM =============================== Prepare Domain ---------------------------- 1. Choose a base domain or subdomain for Netmaker. If you own **example.com**, this should be something like **netmaker.example.com** - You must point your wildcard domain to the public IP of your VM, e.x: *.example.com --> 2. Add an A record pointing to your VM using your DNS service provider for *.netmaker.example.com (inserting your own subdomain of course). 3. Netmaker will create three subdomains on top of this. For the example above those subdomains would be: - dashboard.netmaker.example.com - api.netmaker.example.com - grpc.netmaker.example.com Moving forward we will refer to your base domain using ****. Replace these references with your domain (e.g. netmaker.example.com). 4. ``nslookup host.`` (inserting your domain) should now return the IP of your VM. 5. Generate SSL Certificates using certbot: ``sudo certbot certonly --manual --preferred-challenges=dns --email your@email.com --server https://acme-v02.api.letsencrypt.org/directory --agree-tos --manual-public-ip-logging-ok -d "*."`` The above command (using your domain instead of ), will prompt you to enter a TXT record in your DNS service provider. Do this, and **wait one minute** before clicking enter, or it may fail and you will have to run the command again. Prepare Firewall ----------------- Make sure firewall settings are appropriate for Netmaker. You need ports 53 and 443. On the server you can run: .. code-block:: sudo ufw allow proto tcp from any to any port 443 && sudo ufw allow 53/udp **Based on your cloud provider, you may also need to set inbound security rules for your server. This will be dependent on your cloud provider. Be sure to check before moving on:** - allow 443/tcp from all - allow 53/udp from all Prepare for DNS ---------------------------------------------------------------- On Ubuntu 20.04, by default there is a service consuming port 53 related to DNS resolution. We need port 53 open in order to run our own DNS server. The below steps will disable systemd-resolved, and insert a generic DNS nameserver for local resolution. .. code-block:: systemctl stop systemd-resolved systemctl disable systemd-resolved vim /etc/systemd/resolved.conf * uncomment DNS and add 8.8.8.8 or whatever reachable nameserver is your preference * * uncomment DNSStubListener and set to "no" * ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf Prepare Nginx ----------------- Nginx will serve the SSL certificate with your chosen domain and forward traffic to netmaker. Get the nginx configuration file: ``wget https://raw.githubusercontent.com/gravitl/netmaker/develop/nginx/netmaker-nginx-template.conf`` Insert your domain in the configuration file and add to nginx: .. code-block:: sed -i 's/NETMAKER_BASE_DOMAIN//g' netmaker-nginx-template.conf sudo cp netmaker-nginx-template.conf /etc/nginx/conf.d/.conf nginx -t && nginx -s reload systemctl restart nginx 4. Install Netmaker ==================== Prepare Templates ------------------ .. code-block:: wget https://raw.githubusercontent.com/gravitl/netmaker/develop/compose/docker-compose.quickstart.yml sed -i 's/NETMAKER_BASE_DOMAIN//g' docker-compose.quickstart.yml sed -i 's/SERVER_PUBLIC_IP//g' docker-compose.quickstart.yml Generate a unique master key and insert it: .. code-block:: tr -dc A-Za-z0-9 /g' docker-compose.quickstart.yml Start Netmaker ---------------- ``sudo docker-compose -f docker-compose.quickstart.yml up -d`` navigate to dashboard. to see your nginx instance. To troubleshoot issues, start with: ``docker logs netmaker`` Or check out the :doc:`troubleshoooting docs <./troubleshoot>`.