docs: describe the strict configuration and its generated reference

Updates #3567
Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-17 11:20:18 +00:00
1 parent f5f05440b3
commit 36917c0787
8 files changed
+77 -49

No files matched your search

+15 -2
View File
@@ -24,8 +24,21 @@ Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The c
cd ./headscale
```
1. Download the example configuration for your chosen version and save it as: `$(pwd)/config/config.yaml`. Adjust the
configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
1. Write a configuration to `./config/config.yaml`. `server_url`, the URL clients reach headscale at, is the only key
without a default, so one line is a configuration:
```shell
echo 'server_url: https://headscale.example.com' > ./config/config.yaml
```
Or write the example configuration of your chosen version, every key with its default and documentation, and set
`server_url` in it. See [Configuration](../../ref/configuration.md) for details.
```shell
docker run --rm headscale/headscale:<VERSION> generate config > ./config/config.yaml
```
The published port 9090 serves `/metrics` only with `metrics_listen_addr: 0.0.0.0:9090` in the configuration.
1. Start headscale from within the previously created `./headscale` directory:
+7 -11
View File
@@ -24,8 +24,9 @@ distributions are Ubuntu 22.04 or newer, Debian 12 or newer.
sudo apt install ./headscale.deb
```
1. [Configure headscale by editing the configuration file](../../ref/configuration.md). An up-to date example
configuration file is also available in `/usr/share/doc/headscale/examples/config-example.yaml`:
1. [Configure Headscale by editing the configuration file](../../ref/configuration.md). A new install will find the
default configuration file under `/etc/headscale/config.yaml`. Set `server_url`. A copy of the shipped file is in
`/usr/share/doc/headscale/examples/config-example.yaml`:
```shell
sudo nano /etc/headscale/config.yaml
@@ -82,11 +83,13 @@ managed by systemd.
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.
1. Generate a default configuration and write it to `/etc/headscale/config.yaml`, then adjust it to suit your needs.
Set `server_url`. Check the configuration with `headscale check config`. See
[Configuration](../../ref/configuration.md) for details.
```shell
sudo mkdir -p /etc/headscale
headscale generate config | sudo tee /etc/headscale/config.yaml
sudo nano /etc/headscale/config.yaml
```
@@ -94,13 +97,6 @@ managed by systemd.
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