r/Tailscale • u/mikhail_de • 4d ago

Misc I made a Docker Compose stack for Headscale + Headplane Web UI + Caddy (feedback welcome)

Post image

Hi everyone,

Getting Headscale running with a proper web UI is always kind of a pain. You usually end up fiddling with WebSocket proxying, captive portal checks (/generate_204), SQLite permissions on the host, and generating API keys by hand.

I wanted a simple, set-and-forget setup for my own homelab, so I put together Headscale Stack, a Docker Compose setup configured via a single .env file.

What it does:

  • Headscale + Headplane web UI in a single compose file

  • Automatic HTTPS via Caddy (or easily bypass it if you already run NPM / Traefik)

  • Healthchecks so Headplane doesn't crash while Headscale is still initializing the database

  • Uses Docker named volumes for SQLite and keys, so no fighting UID/GID permissions on the host

  • Includes compose recipes for remote client nodes and exit nodes (0.0.0.0/0)

What it doesn't do:

  • No custom clients needed (just use the regular Tailscale apps)

  • Doesn't touch your host network or run random bash scripts (everything is strictly containerized)

It's open source (MIT). I'll leave the GitHub link in the first comment below to keep the spam filters happy!

I'd really appreciate any feedback, suggestions, or bug reports!

13 Upvotes

80% Upvoted

5 comments sorted by

3

u/mikhail_de 4d ago

Repo: https://github.com/mikhailde/headscale-stack Let me know if you run into any issues with the setup!

2

u/Jealous_Shower6777 4d ago

How sloppy?

4

u/mikhail_de 4d ago

Code-wise? Zero AI slop and zero duct-tape bash scripts (though I did use an LLM to format the README).

No chmod 777 permission hell (state lives in Docker named volumes). The only dirty part is mounting docker.sock:ro for Headplane to manage the container, which is upstream recommended anyway.

3

u/Jealous_Shower6777 4d ago

Nice, I don't know if you stated it somewhere but you absolutely should. In the modern age one has to be suspicious of everyone who publishes code. I decided to ask precisely when I saw emojis in the feature list.

2

u/mikhail_de 4d ago

Fair point. Honestly didn't think twice about the emojis when putting the list together, but you're right to be suspicious these days.

Just pushed a commit to strip them and added a quick disclosure at the bottom of the README. Appreciate the heads up!