Headscale on an immutable Docker image

Deploy Headscale using a "serverless" immutable docker image with real-time Litestream database backup and (by default) inbuilt Caddy SSL termination, using a miniscule Alpine Linux base image. Provides a stateless headscale-admin panel at /admin/.

Included upstream versions

Tool	Version
Alpine Linux	v3.21.3
Headscale	v0.25.1
Headscale-Admin	v0.25.2
Litestream	v0.3.13
Caddy	v2.9.1

Versioning

Because of the mix of upstream tools included, this project will be tagged using semantic versioning - YYYY.MM.REVISION.

All development should be done against the develop branch, main is deemed "stable".

Requirements

• Cloudflare DNS for ACME DNS-01 authentication (Can be deliberately disabled to use HTTP-01 authentication instead, or HTTPS can be disabled entirely if you plan to use an external termination point.)
• S3(Alike)/Azure for Litestream (Can be deliberately disabled for full ephemerality)

Installation

Populate your environment variables according to templates/secrets.template.env

The container entrypoint script will guide you on any errors.

Deployment and user creation

Once app is deployed and green, generate an API Key in order to use the admin interface.

headscale apikeys create

Navigate to the admin gui on /admin/ and set up your groups, ACLs, tags etc.

Final configuration

Now that Headscale is running, to have a 100% reproducible setup we need to ensure that private noise key generated during installation is persisted. Within the same console from previous step, print out the server's key:

cat /data/noise_private.key

Then set HEADSCALE_NOISE_PRIVATE_KEY to the value obtained above.

Note that applying this will cause your application to restart, but afterwards no other change will be necessary.

Known to run on

• Azure Container Apps
• Fly.io
• ??? Let us know!