ToDo

• Develop a more robust integration system for complex network setups. [Not planned]
• Enhance logging and monitoring capabilities for better observability. []
• Explore security enhancements and vulnerability checks.

Disclaimer

Headscale, as a self-hosted control server, does not inherently solve all network security challenges. It's intended to simplify the management of Tailscale nodes within a private network. Network administrators should still apply best practices for security and monitor their network's activity.

Considerations

Running Headscale as a Docker container provides certain advantages, such as ease of deployment and isolation. However, as with any network component, it should be deployed carefully within the context of your network's security architecture.

Usage

First, create a directory for the Headscale container configuration:

mkdir -p ./headscale/

Then, edit the Docker Compose file:

nano ./headscale/docker-compose.yml

Environment Variables and Defaults

Variable	Description	Default Value
SERVER_URL	URL that clients will connect to	http://127.0.0.1:8080
LISTEN_ADDR	Address for the server to listen on	127.0.0.1:8080
METRICS_LISTEN_ADDR	Address for listening to metrics	127.0.0.1:9090
GRPC_LISTEN_ADDR	Address for listening for gRPC	127.0.0.1:50443
DB_TYPE	Type of database to use	sqlite3
DB_PATH	Path to the database file	/var/lib/headscale/db.sqlite

Extended Variables and Defaults

Variable Name	Description	Example Value
SERVER_URL	The URL that clients will connect to	http://127.0.0.1:8080
LISTEN_ADDR	Address for the server to listen on	127.0.0.1:8080
METRICS_LISTEN_ADDR	Address for listening to metrics	127.0.0.1:9090
GRPC_LISTEN_ADDR	Address for listening for gRPC	127.0.0.1:50443
GRPC_ALLOW_INSECURE	Allow gRPC to run in INSECURE mode	false
NOISE_PRIVATE_KEY_PATH	Path to the Noise private key	/var/lib/headscale/noise_private.key
IP_PREFIXES	List of IP prefixes to allocate tailaddresses from	["fd7a:115c:a1e0::/48", "100.64.0.0/10"]
DERP_ENABLED	Whether to enable DERP server	false
DERP_REGION_ID	Region ID for the DERP server	999
DERP_STUN_LISTEN_ADDR	Address for the DERP STUN server to listen on	0.0.0.0:3478
DERP_PRIVATE_KEY_PATH	Path to the DERP server private key	/var/lib/headscale/derp_server_private.key
ACME_URL	URL to ACME directory for Let's Encrypt	https://acme-v02.api.letsencrypt.org/directory
ACME_EMAIL	Email to register with ACME provider	example@email.com
TLS_LETSENCRYPT_HOSTNAME	Domain name for TLS certificate	mydomain.com
TLS_LETSENCRYPT_CACHE_DIR	Path to store certificates and metadata for Let's Encrypt	/var/lib/headscale/cache
DB_TYPE	Database type (e.g., sqlite3, postgres)	sqlite3
DB_PATH	Path to the database file (for sqlite3)	/var/lib/headscale/db.sqlite

To use these variables in your config-example.yaml, you would format them like this:

server_url: ${SERVER_URL}
listen_addr: ${LISTEN_ADDR}
metrics_listen_addr: ${METRICS_LISTEN_ADDR}
...

Note:

These variables can be customized to fit your network setup. Ensure that they align with your network's configuration and security policies.

docker-compose.yml

version: '3.8'

services:
  headscale:
    image: headscale/headscale:latest
    volumes:
      - ./headscale/config:/etc/headscaled
    environment:
      - SERVER_URL=${SERVER_URL}
      - LISTEN_ADDR=${LISTEN_ADDR}
      - METRICS_LISTEN_ADDR=${METRICS_LISTEN_ADDR}
      - GRPC_LISTEN_ADDR=${GRPC_LISTEN_ADDR}
      - DB_TYPE=${DB_TYPE}
      - DB_PATH=${DB_PATH}

Notes:

• Customize the environment variables in the docker-compose.yml file as needed.
• You may need to adjust port mappings based on your specific network setup.
• Ensure that the Headscale container's configuration aligns with your security policies and network architecture.