docs(config): make container_label the default method for Docker integration

Update the example configuration to use container_label as the preferred
method for discovering the Headscale container. container_name is now
commented out and marked as an optional fallback for static setups.
Update compose.yaml and docs to reflect this change.

Signed-off-by: Georgios Ntoutsos <gntouts@nubificus.co.uk>
This commit is contained in:
Georgios Ntoutsos 2025-04-24 21:16:16 +03:00
parent 5b3b4eb240
commit e052383ee2
3 changed files with 16 additions and 14 deletions

View File

@ -10,6 +10,8 @@ services:
headscale:
image: "headscale/headscale:0.25.1"
container_name: "headscale"
labels:
- com.headplane.selector=headscale
restart: "unless-stopped"
command: "serve"
networks:

View File

@ -47,14 +47,14 @@ headscale:
integration:
docker:
enabled: false
# The name (or ID) of the container running Headscale
container_name: "headscale"
# The label that will be used to identify the container running Headscale.
# This can be omitted if the container name is known in advance and is not
# subject to changes.
# Preferred method: use container_label to dynamically discover the Headscale container.
container_label:
name: "workload.headscale.io/name"
name: "com.headplane.selector"
value: "headscale"
# Optional fallback: directly specify the container name (or ID)
# of the container running Headscale
# container_name: "headscale"
# The path to the Docker socket (do not change this if you are unsure)
# Docker socket paths must start with unix:// or tcp:// and at the moment
# https connections are not supported.

View File

@ -70,14 +70,14 @@ you build the container yourself or run Headplane in Bare-Metal mode.
> setting up your `config.yaml` file to the appropriate values.
## Docker Integration
The Docker integration is the easiest to setup, as it only requires the Docker socket
to be mounted into the container along with some configuration. As long as Headplane
has access to the Docker socket and the name of the Headscale container, it will
automatically propagate config and DNS changes to Headscale without any additional
configuration. Additionally, instead of specifying the name of the Headscale
container, it is possible to use a label to dynamically deduce the container
name. This can be useful if the container name changes frequently, or is not
known in advance.
The Docker integration is the easiest to set up, as it only requires mounting the
Docker socket into the container along with some basic configuration. Headplane
uses Docker labels to discover the Headscale container. As long as Headplane has
access to the Docker socket and can identify the Headscale container—either by
label or name—it will automatically propagate configuration and DNS changes to
Headscale without any additional setup. Alternatively, instead of using a label
to dynamically determine the container name, it is possible to directly specify
the container name.
## Native Linux (/proc) Integration
The `proc` integration is used when you are running Headscale and Headplane on