on posts

Hosting Headscale In a Container With Docker

What is headscale?

Headscale is an open-source, self-hosted implementation of the Tailscale control server.

Headscale aims to implement a self-hosted, open-source alternative to the Tailscale control server. Headscale aims to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrower scope, a single Tailnet, suitable for personal use, or a small open-source organization.

In this guide, we will be showing how to set up and run headscale in a container.

Prerequisites

Configure and run headscale

  1. Prepare a directory on the host Docker node in your directory of choice, used to hold headscale configuration and the SQLite database:
  • mkdir -p ./headscale/config
  • cd ./headscale
  1. Download the example configuration for your chosen version and save it as: /headscale/config/config.yaml
NOTE: AS OF NOVEMBER 2024 THERE ARE PROBLEMS WITH THE DEFAULT CONFIG SO I HAVE SHARED MY OWN CONFIG HERE
server_url: https://example.xyz
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 127.0.0.1:9090
grpc_listen_addr: 0.0.0.0:50443
grpc_allow_insecure: false
noise:
  private_key_path: /var/lib/headscale/noise_private.key
prefixes:
  v6: fd7a:115c:a1e0::/48
  v4: 100.64.0.0/10
  allocation: sequential
derp:
  server:
    enabled: false
    region_id: 999
    region_code: "headscale"
    region_name: "Headscale Embedded DERP"
    stun_listen_addr: "0.0.0.0:3478"
    private_key_path: /var/lib/headscale/derp_server_private.key
    automatically_add_embedded_derp_region: true
    ipv4: 1.2.3.4
    ipv6: 2001:db8::1
  urls:
    - https://controlplane.tailscale.com/derpmap/default
  paths: []
  auto_update_enabled: true
  update_frequency: 24h
disable_check_updates: false
ephemeral_node_inactivity_timeout: 30m
database:
  type: sqlite
  debug: false
  gorm:
    prepare_stmt: true
    parameterized_queries: true
    skip_err_record_not_found: true
    slow_threshold: 1000
  sqlite:
    path: /var/lib/headscale/db.sqlite
    write_ahead_log: true
acme_url: https://acme-v02.api.letsencrypt.org/directory
acme_email: ""
tls_letsencrypt_hostname: ""
tls_letsencrypt_cache_dir: /var/lib/headscale/cache
tls_letsencrypt_challenge_type: HTTP-01
tls_letsencrypt_listen: ":http"
tls_cert_path: ""
tls_key_path: ""
log:
  format: text
  level: info
policy:
  mode: file
  path: ""
dns:
  magic_dns: true
  base_domain: tailnet.bidonov.xyz
  nameservers:
    global:
      - 1.1.1.1
      - 1.0.0.1
      - 2606:4700:4700::1111
      - 2606:4700:4700::1001
    split:
      {}
      # foo.bar.com:
      #   - 1.1.1.1
      # darp.headscale.net:
      #   - 1.1.1.1
      #   - 8.8.8.8
  search_domains: []
  extra_records: []
#  use_username_in_magic_dns: false
unix_socket: /var/run/headscale/headscale.sock
unix_socket_permission: "0770"
logtail:
  enabled: false
randomize_client_port: false
  1. Start the headscale server while working in the host headscale directory:
docker run \
  --name headscale \
  --detach \
  --volume $(pwd)/config:/etc/headscale/ \
  --volume $(pwd)/lib:/var/lib/headscale \
  --volume $(pwd)/run:/var/run/headscale \
  --publish 0.0.0.0:8080:8080 \
  --publish 127.0.0.1:9090:9090 \
  headscale/headscale:v0.23.0 \
  serve
  1. Verify headscale is running:

Follow the container logs:

  • docker logs --follow headscale

Verify running containers:

  • docker ps

Verify headscale is available:

  • curl http://127.0.0.1:9090/metrics
  1. Create a user (tailnet):
docker exec -it headscale \
  headscale users create myfirstuser

Register a machine (normal login)

On a client machine, execute the tailscale login command:

  • tailscale up --login-server YOUR_HEADSCALE_URL

To register a machine when running headscale in a container, take the headscale command and pass it to the container:

docker exec -it headscale \
  headscale nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>

Register machine using a pre-authenticated key

Generate a key using the command line:

docker exec -it headscale \
  headscale preauthkeys create --user myfirstuser --reusable --expiration 24h

This will return a pre-authenticated key that can be used to connect a node to headscale during the tailscale command:

  • tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>

Debugging headscale running in Docker

The headscale/headscale Docker container is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug your application running in the Docker container, you can use the -debug variant, for example headscale/headscale:x.x.x-debug.

Running the debug Docker container

To run the debug Docker container, use the exact same commands as above, but replace headscale/headscale:x.x.x with headscale/headscale:x.x.x-debug (x.x.x is the version of headscale). The two containers are compatible with each other, so you can alternate between them.

Executing commands in the debug container

The default command in the debug container is to run headscale, which is located at /ko-app/headscale inside the container.

Additionally, the debug container includes a minimalist Busybox shell.

To launch a shell in the container, use:

docker run -it headscale/headscale:x.x.x-debug sh

You can also execute commands directly, such as ls /ko-app in this example:

docker run headscale/headscale:x.x.x-debug ls /ko-app

Using docker exec -it allows you to run commands in an existing container.