Headnet

A web-ui for Headscale with a focus on easy ACL management thru 3D network visualization

Deploy

Headnet comes packaged in different ways ready to deploy

Docker

Distroless docker container running deno

Tags

• latest Latest stable release
• x.x.x Release images
• x.x.x-pre Pre-release images (potentially unstable)
• unstable Built on every push to main

Docker run

docker run -d -p 3000:3000 ghcr.io/rickli-cloud/headnet:latest

Docker compose

Save this as docker-compose.yaml:

version: '3.9'
name: headnet
services:
  headnet:
    image: ghcr.io/rickli-cloud/headnet:${HEADNET_VERSION:-latest}
    container_name: headnet
    pull_policy: always
    restart: always
    ports:
      - 0.0.0.0:3000:3000/tcp
    environment:
      PUBLIC_MOCK_ENABLED: 'true' # Demo mode enabled

Start it up:

docker compose up -d

Static / Node

For all releases there are zip archives provided for each build target

The node server is not capable of TLS and is best used in combination with a reverse proxy. This does not pose a big security risk (assuming the internal network is somewhat secure) as no sensitive data is directly transmitted to this server.

Desktop application

For all releases there are standalone executables or installers provided for different platforms. Thanks to a special client integration it is possible to completely circumvent any CORS restrictions

Environment configuration

Note

When using the static build target the environment can be configured on buildtime or by modifying the /_app/env.js file. Example to enable mocking:

export const env = { PUBLIC_MOCK_ENABLED: 'true' };

Base path

Only affective during buildtime

# linux
export BASE_PATH="/admin"
# windows
$env:BASE_PATH="/admin"

Build target

Only affective during buildtime

With the help of SvelteKit adapters it is possible to target different environments. For now this includes:

• node Ready to serve requests running node or deno
• static Can be served using almost any webserver capable of serving static files (single page application)
• auto Let SvelteKit figure it out

# linux
export BUILD_TARGET="node"
# windows
$env:BUILD_TARGET="node"

Development proxy

Only affective during development

To circumvent CORS issues vite provides a dev proxy leading to your headscale instance. To enable this you have to define your headscale host as a environment variable

# linux
export HEADSCALE_HOST="https://headscale.example.com"
# windows
$env:HEADSCALE_HOST="https://headscale.example.com"

Mocking

Mock the whole API with the help of a service worker. This enables "demo mode"

# linux
export PUBLIC_MOCK_ENABLED="false"
# windows
$env:PUBLIC_MOCK_ENABLED="false"

Install dependencies

Dependencies are required for building or developing

deno install

Building

Node / Static

Create a production build:

deno task build

Tip

You can use docker for building if you do not want to / cant install deno:

docker run -it --rm --workdir /app -v ${PWD}:/app:rw --entrypoint /bin/sh denoland/deno:latest

Tauri

Needs specific configuration to work properly:

• BASE_PATH = "/"
• BUILD_TARGET = "static"

deno task tauri build

Developing

Start a development server:

deno task dev

Stack

Some of the major projects used:

• deno 2
• tauri 2
• svelte 5
• shadcn
• 3d-force-graph
• json-ast-comments
• openapi-typescript
• mock service worker

Note

Deno provides additional functionality such as automatic types for third party modules. NodeJS does not support this and will not work with this project during development / building.