hsman/README.md

HSMAN

Headscale admin application

Intro

HSMAN is a Flask application (with some nice javascript) to administer an headscale installation.

Currently it can manage users, nodes, routes, but I plan to add support for managing API keys too.

Deployment

You can run the Flask application as any other Flask app, using flask run inside the root directory, or using gunicorn and the provided gunicorn.conf.py file, or you can build a docker image, using the files inside docker directory and then use the resulting docker image

Settings

There are some settings that must/can be provided to the application:

Variable	Usage	Default
APPLICATION_ROOT	Base URI path for the app	/
HSMAN_SECRET_KEY	Flask app secret key
HSMAN_ADMIN_GROUPS	Comma separated list of user groups that are considered admins
HSMAN_OIDC_CLIENT_ID	OIDC client ID
HSMAN_OIDC_CLIENT_SECRET	OIDC clietn secret
HSMAN_OIDC_URL	OIDC server URL
HSMAN_OIDC_REDIRECT_URI	OIDC redirect URI
HSAPI_SERVER	Headscale server URL
HSAPI_API_TOKEN	API token/key to access headscale server

The last two variables are then fed to hsapi-client, the module that we use to interact with Headscale APIs.

Requirements

So far HSMAN requires to authenticate via OIDC, that is a secure setup, that you should implement on headscale too. You can use your own iDP, like keycloak or dex or use external iDP, like Google or Github, but the setup of this part is left to you, so far, we will document it later.

In the future we could add support to run HSMAN without and iDP/OIDC server, but don't hold your breath ;)