How to Install Headscale on Linux Mint

Headscale is a self-hosted WireGuard network designed to provide a secure communication channel for various devices connected to the same network. In this tutorial, we will discuss how to install Headscale on Linux Mint.

Prerequisites

Before we proceed with the installation, we must ensure that we have the following:

  • A Linux Mint system with sudo privileges
  • Access to the terminal on the system
  • Basic knowledge of the Linux command line interface

Installation Steps

Follow the steps below to install Headscale on Linux Mint:

Step 1: Install WireGuard

We must install WireGuard first to use it with Headscale. We can do this by following the steps below:

  • Launch the terminal on your Linux Mint system.
  • Add the WireGuard repository key, so the system can verify that the package is authentic:
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 04EE7237B7D453EC
  • Add the WireGuard repository to the system sources list:
sudo add-apt-repository ppa:wireguard/wireguard
  • Update the system to apply the recent changes:
sudo apt-get update
  • Install WireGuard on the system:
sudo apt-get install wireguard

Step 2: Install Headscale

Once we have WireGuard installed, we can proceed with the Headscale installation. To do it, follow the steps below:

  • Launch the terminal and enter the following command to download the latest Headscale release:
wget https://github.com/juanfont/headscale/releases/latest/download/headscale-linux-amd64.tar.gz
  • Extract the downloaded package by running:
tar -xf headscale-linux-amd64.tar.gz
  • Move the headscale binary to the /usr/local/bin directory:
sudo mv headscale /usr/local/bin
  • Create a Headscale configuration file named config.hcl. We can use any editor of our choice, for instance, vim:
sudo vim /etc/headscale/config.hcl
  • Once we have the file open, copy and paste the following YAML code snippet for Headscale configuration:
automigrate = false # Set to true if the database does not exist yet

storage "file" {
  path = "/etc/headscale/database.db"
}

node {
  name = "$NODE_NAME_HERE"
  region = "$REGION_NAME_HERE"
  listen_port = 51820
  public_key = "$GENERATED_PUBLIC_KEY_HERE"
  private_key = "$GENERATED_PRIVATE_KEY_HERE"
}

control {
  listen_addr = "$CONTROL_IP_ADDRESS_HERE:PORT_4444"
}

migrations_path = "/usr/local/bin/headscale/migrations/"
  • Replace the following placeholders in the configuration file with your preferred values:
$NODE_NAME_HERE # Replace with the name of your node.
$REGION_NAME_HERE # Replace with the name of your region.
$GENERATED_PUBLIC_KEY_HERE # Replace with the public key created above.
$GENERATED_PRIVATE_KEY_HERE # Replace with the private key created above.
$CONTROL_IP_ADDRESS_HERE # Replace with the IP address of the system.
  • Save and exit the configuration file.

Step 3: Start the Headscale Server

After the configuration file is set up, run the Headscale server by entering the following command:

sudo headscale serve -config /etc/headscale/config.hcl

Step 4: Set up Client Devices

Now that the Headscale server is running, we need to set up our client devices to use the network. The exact instructions will depend on the device and platform, but the general steps are:

  • Install WireGuard on the client device.
  • Create a WireGuard configuration file with the appropriate settings that match our Headscale configuration file.
  • Add the configuration to the WireGuard instance on the client device.
  • Connect to the Headscale network.

Conclusion

Headscale can provide a secure communication channel for devices connected to the same network, and its installation is relatively simple. By following the steps in this tutorial, we can quickly set up Headscale on Linux Mint, install WireGuard, and configure set up client devices to connect to the network.