diff --git a/docs/running-headscale-linux-manual.md b/docs/running-headscale-linux-manual.md deleted file mode 100644 index 9ec39b36..00000000 --- a/docs/running-headscale-linux-manual.md +++ /dev/null @@ -1,129 +0,0 @@ -# Running headscale on Linux - -!!! warning "Outdated and advanced" - - This documentation is considered the "legacy"/advanced/manual version of the documentation, you most likely do not - want to use this documentation and rather look at the [distro specific documentation](./running-headscale-linux.md). - -## Goal - -This documentation has the goal of showing a user how-to set up and run `headscale` on Linux. -In additional to the "get up and running section", there is an optional [systemd section](#running-headscale-in-the-background-with-systemd) -describing how to make `headscale` run properly in a server environment. - -## Configure and run `headscale` - -1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases): - - ```shell - wget --output-document=/usr/local/bin/headscale \ - https://github.com/juanfont/headscale/releases/download/v/headscale__linux_ - ``` - -1. Make `headscale` executable: - - ```shell - chmod +x /usr/local/bin/headscale - ``` - -1. Prepare a directory to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database: - - ```shell - # Directory for configuration - - mkdir -p /etc/headscale - - # Directory for Database, and other variable data (like certificates) - mkdir -p /var/lib/headscale - # or if you create a headscale user: - useradd \ - --create-home \ - --home-dir /var/lib/headscale/ \ - --system \ - --user-group \ - --shell /usr/sbin/nologin \ - headscale - ``` - -1. Create a `headscale` configuration: - - ```shell - touch /etc/headscale/config.yaml - ``` - - **(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository. - -1. Start the headscale server: - - ```shell - headscale serve - ``` - - This command will start `headscale` in the current terminal session. - - --- - - To continue the tutorial, open a new terminal and let it run in the background. - Alternatively use terminal emulators like [tmux](https://github.com/tmux/tmux) or [screen](https://www.gnu.org/software/screen/). - - To run `headscale` in the background, please follow the steps in the [systemd section](#running-headscale-in-the-background-with-systemd) before continuing. - -1. Verify `headscale` is running: - Verify `headscale` is available: - - ```shell - curl http://127.0.0.1:9090/metrics - ``` - -## Running `headscale` in the background with systemd - -This section demonstrates how to run `headscale` as a service in the background with [systemd](https://systemd.io/). -This should work on most modern Linux distributions. - -1. Copy [headscale's systemd service file](./packaging/headscale.systemd.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`. - - Note that when running as the headscale user ensure that, either you add your current user to the headscale group: - - ```shell - usermod -a -G headscale current_user - ``` - - or run all headscale commands as the headscale user: - - ```shell - su - headscale - ``` - -1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with path that is writable by the `headscale` user or group: - - ```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 the headscale service: - - ```shell - systemctl status headscale - ``` - - Verify `headscale` is available: - - ```shell - curl http://127.0.0.1:9090/metrics - ``` - -`headscale` will now run in the background and start at boot. diff --git a/docs/setup/install/official.md b/docs/setup/install/official.md index d26aa998..3144d953 100644 --- a/docs/setup/install/official.md +++ b/docs/setup/install/official.md @@ -36,8 +36,82 @@ Ubuntu 20.04 or newer, Debian 11 or newer. sudo systemctl enable --now headscale ``` -1. Check that Headscale is running as intended: +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 headscale 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 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__linux_ + ``` + +1. Make `headscale` executable: + + ```shell + sudo chmod +x /usr/local/bin/headscale + ``` + +1. Add a dedicated 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](../../packaging/headscale.systemd.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 + 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 + ```