mirror of
https://github.com/juanfont/headscale.git
synced 2025-05-23 18:41:52 -04:00
4a941a2cb4
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
118 lines
3.9 KiB
Markdown
118 lines
3.9 KiB
Markdown
# 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](https://github.com/juanfont/headscale/releases).
|
|
|
|
## 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](https://github.com/juanfont/headscale/releases/latest) for your platform (`.deb` for Ubuntu and Debian).
|
|
|
|
```shell
|
|
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"
|
|
```
|
|
|
|
1. Install headscale:
|
|
|
|
```shell
|
|
sudo apt install ./headscale.deb
|
|
```
|
|
|
|
1. [Configure headscale by editing the configuration file](../../ref/configuration.md):
|
|
|
|
```shell
|
|
sudo nano /etc/headscale/config.yaml
|
|
```
|
|
|
|
1. Enable and start the headscale service:
|
|
|
|
```shell
|
|
sudo systemctl enable --now headscale
|
|
```
|
|
|
|
1. Verify that headscale is running as intended:
|
|
|
|
```shell
|
|
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](../requirements.md#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](https://github.com/juanfont/headscale/releases):
|
|
|
|
```shell
|
|
sudo wget --output-document=/usr/local/bin/headscale \
|
|
https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
|
|
```
|
|
|
|
1. Make `headscale` executable:
|
|
|
|
```shell
|
|
sudo chmod +x /usr/local/bin/headscale
|
|
```
|
|
|
|
1. Add a dedicated local user to run headscale:
|
|
|
|
```shell
|
|
sudo useradd \
|
|
--create-home \
|
|
--home-dir /var/lib/headscale/ \
|
|
--system \
|
|
--user-group \
|
|
--shell /usr/sbin/nologin \
|
|
headscale
|
|
```
|
|
|
|
1. 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](../../ref/configuration.md) for details.
|
|
|
|
```shell
|
|
sudo mkdir -p /etc/headscale
|
|
sudo nano /etc/headscale/config.yaml
|
|
```
|
|
|
|
1. Copy [headscale's systemd service file](https://github.com/juanfont/headscale/blob/main/packaging/systemd/headscale.service)
|
|
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`.
|
|
|
|
1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with a path that is writable by the
|
|
`headscale` user or group:
|
|
|
|
```yaml title="config.yaml"
|
|
unix_socket: /var/run/headscale/headscale.sock
|
|
```
|
|
|
|
1. Reload systemd to load the new configuration file:
|
|
|
|
```shell
|
|
systemctl daemon-reload
|
|
```
|
|
|
|
1. Enable and start the new headscale service:
|
|
|
|
```shell
|
|
systemctl enable --now headscale
|
|
```
|
|
|
|
1. Verify that headscale is running as intended:
|
|
|
|
```shell
|
|
systemctl status headscale
|
|
```
|