Caddy & Headscale Setup Guide

This project uses Caddy as a reverse proxy with OIDC authentication and Headscale as a self-hosted coordination server. Caddy and Headscale are both run using Docker Compose.

Prerequisites

Before you begin, make sure you have the following tools installed:

• Docker
• Docker Compose
• Cloudflare API Token
  • This configuration is uing Cloudflare TLS Challenge and assumes DNS is managed at Cloudflare
  • Ensure DNS A/AAAA record is setup and pointing at your server's public IP address
• Caddy (Optional: only needed to generate hash password for basic auth)

Setup Instructions

1. Clone the Repository

Start by cloning this repository to your local machine:

git clone https://github.com/Black-Relay/caddy-headscale.git
cd caddy-headscale

2. Create Web-UI Password

Create a password for headscale-ui

caddy hash-password --plaintext "your-password"

3. Configure the .env File

Copy the .env.example file in the root of the project and populate

cp .env.example .env

4. Create the Docker Network for Caddy

docker network create caddy_network

5. Update the Headscale config

Update the following paramaters within the headscale/container-config/config.yaml:

FQDN of your Headscale Server

• server_url: https://DOMAIN_NAME

If using OIDC (below is a Microsoft EntraID example)

• issuer: "https://login.microsoftonline.com//v2.0"
• client_secret: "SECRET"
• client_id: "CLIENT_ID"

6. Run the docker container

docker compose up -d