MyFavMirrors/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2025-05-23 10:31:53 -04:00
Code Issues Packages Projects Releases Wiki Activity
headscale/docs/setup/install/official.md
Florian Preinstorfer 4a941a2cb4 Refactor Debian/Ubuntu package 
Move files for packaging outside the docs directory into its own
packaging directory. Replace the existing postinstall and postremove
scripts with Debian maintainerscripts to behave more like a typical
Debian package:

* Start and enable the headscale systemd service by default
* Does not print informational messages
* No longer stop and disable the service on updates

This package also performs migrations for all changes done in previous
package versions on upgrade:

* Set login shell to /usr/sbin/nologin
* Set home directory to /var/lib/headscale
* Migrate to system UID/GID

The package is lintian-clean with a few exceptions that are documented
as excludes and it passes puipars (both tested on Debian 12).

The following scenarious were tested on Ubuntu 22.04, Ubuntu 24.04,
Debian 11, Debian 12:

* Install
* Install same version again
* Install -> Remove -> Install
* Install -> Purge -> Install
* Purge
* Update from 0.22.0
* Update from 0.26.0

See: #2278
See: #2133
Fixes: #2311
2025-05-21 15:40:32 +02:00

3.9 KiB
Raw Blame History

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 20.04 or newer, Debian 11 or newer.

  1. Download the latest headscale package for your platform (.deb for 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"

  2. Install headscale:

    sudo apt install ./headscale.deb

  3. Configure headscale by editing the configuration file:

    sudo nano /etc/headscale/config.yaml

  4. Enable and start the headscale service:

    sudo systemctl enable --now headscale

  5. Verify that headscale is running as intended:

    sudo systemctl status headscale

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.

  1. Download the latest headscale binary from GitHub's release page:

    sudo wget --output-document=/usr/local/bin/headscale \
https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>

  2. Make headscale executable:

    sudo chmod +x /usr/local/bin/headscale

  3. 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

  4. Download the example configuration for your chosen version and save it as: /etc/headscale/config.yaml. Adjust the configuration to suit your local environment. See Configuration for details.

    sudo mkdir -p /etc/headscale
sudo nano /etc/headscale/config.yaml

  5. Copy headscale's systemd service file to /etc/systemd/system/headscale.service and adjust it to suit your local setup. The following parameters likely need to be modified: ExecStart, WorkingDirectory, ReadWritePaths.

  6. In /etc/headscale/config.yaml, override the default headscale unix socket with a path that is writable by the headscale user or group:

    unix_socket: /var/run/headscale/headscale.sock

  7. Reload systemd to load the new configuration file:

    systemctl daemon-reload

  8. Enable and start the new headscale service:

    systemctl enable --now headscale

  9. Verify that headscale is running as intended:

    systemctl status headscale