4.1 KiB
Official releases
Official releases for headscale are available as binaries for various platforms and DEB packages for Debian and Ubuntu. Both are available on the GitHub releases page.
Using packages for Debian/Ubuntu (recommended)
It is recommended to use our DEB packages to install headscale on a Debian based system as those packages configure a local user to run headscale, provide a default configuration and ship with a systemd service file. Supported distributions are Ubuntu 22.04 or newer, Debian 12 or newer.
-
Download the latest headscale package for your platform (
.debfor Ubuntu and Debian).HEADSCALE_VERSION="" # See above URL for latest version, e.g. "X.Y.Z" (NOTE: do not add the "v" prefix!) HEADSCALE_ARCH="" # Your system architecture, e.g. "amd64" wget --output-document=headscale.deb \ "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb" -
Install headscale:
sudo apt install ./headscale.deb -
Configure Headscale by editing the configuration file. A new install will find the default configuration file under
/etc/headscale/config.yaml. Setserver_url. A copy of the shipped file is in/usr/share/doc/headscale/examples/config-example.yaml:sudo nano /etc/headscale/config.yaml -
Restart headscale to pick up configuration changes:
sudo systemctl restart headscale -
Verify that headscale is running as intended:
sudo systemctl status headscale
Continue on the getting started page to register your first machine.
Using standalone binaries (advanced)
!!! warning "Advanced"
This installation method is considered advanced as one needs to take care of the local user and the systemd
service themselves. If possible, use the [DEB packages](#using-packages-for-debianubuntu-recommended) or a
[community package](community.md) instead.
This section describes the installation of headscale according to the Requirements and assumptions. Headscale is run by a dedicated local user and the service itself is managed by systemd.
-
Download the latest
headscalebinary from GitHub's release page:sudo wget --output-document=/usr/bin/headscale \ https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH> -
Make
headscaleexecutable:sudo chmod +x /usr/bin/headscale -
Add a dedicated local user to run headscale:
sudo useradd \ --create-home \ --home-dir /var/lib/headscale/ \ --system \ --user-group \ --shell /usr/sbin/nologin \ headscale -
Generate a default configuration and write it to
/etc/headscale/config.yaml, then adjust it to suit your needs. Setserver_url. Check the configuration withheadscale check config. See Configuration for details.sudo mkdir -p /etc/headscale headscale generate config | sudo tee /etc/headscale/config.yaml sudo nano /etc/headscale/config.yaml -
Copy headscale's systemd service file to
/etc/systemd/system/headscale.serviceand adjust it to suit your local setup. The following parameters likely need to be modified:ExecStart,WorkingDirectory,ReadWritePaths. -
Reload systemd to load the new configuration file:
systemctl daemon-reload -
Enable and start the new headscale service:
systemctl enable --now headscale -
Verify that headscale is running as intended:
systemctl status headscale
Continue on the getting started page to register your first machine.