juanfont/headscale
1
1
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2024-11-15 12:11:29 +08:00
Code Issues Projects Releases Packages Wiki Activity
headscale/docs/setup/install/official.md
nblock 8c7d8ee34f
Restructure headscale documentation (#2163) 
* 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
2024-10-10 15:24:04 +02:00

3.8 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 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 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. 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:

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