Skip to content

Latest commit

 

History

History
76 lines (51 loc) · 4.02 KB

README.md

File metadata and controls

76 lines (51 loc) · 4.02 KB

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 Upstream Repository Version
Alpine Linux Alpine Linux Repo v3.23.3
Headscale Headscale Repo v0.28.0
Headscale-Admin Headscale-Admin Repo 7da5aa3
Litestream Litestream Repo 0.5.9
Caddy Caddy Repo v2.11.1

DEPRECATION NOTICE: Headscale-Admin is deprecated in this release as it appears to have been abandoned by upstream. We have moved to a fork with patches so we can take advantage of the improvements in Headscale's 0.28.X release, but are actively testing replacement admin panels before Headscale's 0.29.X releases.

Versioning

Because of the mix of upstream tools included, this project will be tagged using the versioning style 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, or if you plan to use persistent storage)

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!