Headscale-UI

A web frontend for the headscale Tailscale-compatible coordination server.

Installation

Headscale-UI is currently released as a static site: just take the release and host with your favorite web server. Headscale-UI expects to be served from the /web path to avoid overlap with headscale on the same domain. Note that due to CORS (see https://github.com/juanfont/headscale/issues/623), headscale UI must be served on the same subdomain, or CORS headers injected via reverse proxy.

Docker Installation

If you are using docker, you can install headscale alongside headscale-ui, like so:

version: '3.5'
services:
  headscale:
    image: headscale/headscale:latest-alpine
    container_name: headscale
    volumes:
      - ./container-config:/etc/headscale
      - ./container-data/data:/var/lib/headscale
    # ports:
      # - 27896:8080
    command: headscale serve
    restart: unless-stopped
  headscale-ui:
    image: ghcr.io/gurucomputing/headscale-ui:latest
    restart: unless-stopped
    container_name: headscale-ui
    # ports:
      # - 9443:443

Headscale UI serves on port 443 and uses a self signed cert by default.

Additional Docker Settings

The docker container lets you set the following settings:

Variable	Description	Example
PORT	Sets the port to an alternate value	443

Proxy Settings

You will need a reverse proxy to install headscale-ui on your domain. Here is an example Caddy Config to achieve this:

https://hs.yourdomain.com.au {
	reverse_proxy /web* https://headscale-ui {
		transport http {
			tls_insecure_skip_verify
		}
	}

	reverse_proxy * http://headscale:8080
}

Cross Domain Installation

If you do not want to configure headscale-ui on the same subdomain as headscale, you must intercept headscale traffic via your reverse proxy to fix CORS (see https://github.com/juanfont/headscale/issues/623). Here is an example fix with Caddy, replacing your headscale UI domain with hs-ui.yourdomain.com.au:

hs.yourdomain.com.au {
  @hs-options {
    host hs.yourdomain.com.au
    method OPTIONS
  }
  @hs-other {
    host hs.yourdomain.com.au
  }
  handle @hs-options {
    header {
      Access-Control-Allow-Origin https://hs-ui.yourdomain.au
      Access-Control-Allow-Headers *
      Access-Control-Allow-Methods "POST, GET, OPTIONS, DELETE"
    }
    respond 204
  }
  handle @hs-other {
    reverse_proxy http://headscale:8080 {
      header_down Access-Control-Allow-Origin https://hs-ui.yourdomain.com.au
      header_down Access-Control-Allow-Methods "POST, GET, OPTIONS, DELETE"
      header_down Access-Control-Allow-Headers *
    }
  }
}

Development

see development for details

Style Guide

see style for details

Architecture

See architecture for details