mirror of
https://github.com/juanfont/headscale.git
synced 2024-11-25 11:05:29 +00:00
8c7d8ee34f
* Setup mkdocs-redirects * Restructure existing documentation * Move client OS support into the documentation * Move existing Client OS support table into its own documentation page * Link from README.md to the rendered documentation * Document minimum Tailscale client version * Reuse CONTRIBUTING.md" in the documentation * Include "CONTRIBUTING.md" from the repository root * Update FAQ and index page and link to the contributing docs * Add configuration reference * Add a getting started page and explain the first steps with headscale * Use the existing "Using headscale" sections and combine them into a single getting started guide with a little bit more explanation. * Explain how to get help from the command line client. * Remove duplicated sections from existing installation guides * Document requirements and assumptions * Document packages provided by the community * Move deb install guide to official releases * Move manual install guide to official releases * Move container documentation to setup section * Move sealos documentation to cloud install page * Move OpenBSD docs to build from source * Simplify DNS documentation * Add sponsor page * Add releases page * Add features page * Add help page * Add upgrading page * Adjust mkdocs nav * Update wording Use the term headscale for the project, Headscale on the beginning of a sentence and `headscale` when refering to the CLI. * Welcome to headscale * Link to existing documentation in the FAQ * Remove the goal header and use the text as opener * Indent code block in OIDC * Make a few pages linter compatible Also update ignored files for prettier * Recommend HTTPS on port 443 Fixes: #2164 * Use hosts in acl documentation thx @efficacy38 for noticing this Ref: #1863 * Use mkdocs-macros to set headscale version once
118 lines
3.8 KiB
Markdown
118 lines
3.8 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
|
|
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 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 VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
|
|
```
|
|
|
|
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
|
|
```
|