Bare-Metal Mode

Bare-Metal mode is the most flexible way to deploy Headplane. It allows you to run Headplane on any system without the need for Docker or any other container runtime. This is not recommended, but I understand that everyone has different needs.

It works with both the Simple and Integrated deployment modes. Refer to the section below for instructions on configuring Integrated mode.

Deployment

Requirements:

• Headscale 0.26 or newer (already deployed)
• Node.js 22.16 LTS or newer
• PNPM 10.x
• A finished configuration file (config.yaml)

Before installing Headplane, ensure that /var/lib/headplane exists and is writable by the user that will run the Headplane service. You can create this directory with the following command:

sudo mkdir -p /var/lib/headplane
# Replace headplane:headplane with the appropriate user and group if not root.
sudo chown -R headplane:headplane /var/lib/headplane

Clone the Headplane repository, install dependencies, and build the project:

git clone https://github.com/tale/headplane
cd headplane
git checkout v0.6.0 # Or whatever tag you want to use
pnpm install
pnpm build

Running Headplane

You can start headplane through pnpm start or node build/headplane/server.js. Headplane expects the build directory to be present when running the server. The structure of this folder is very important and should not be tampered with.

Integrated Mode

Since you are running Headplane in Bare-Metal, you most likely also are running Headscale in Bare-Metal. Refer to the Integrated Mode guide for instructions on setting up the integrated mode in Native Linux (/proc).

Changing the Admin Path

Since you are building Headplane yourself, you are able to configure the admin path to be anything you want. When running pnpm build, you can pass the __INTERNAL_PREFIX environment variable to change the admin path. For example:

__INTERNAL_PREFIX=/admin2 pnpm build

Just keep in mind that the admin path is not configurable at runtime, so you will need to rebuild the project if you want to change it. Also, anything aside from /admin is not officially supported and could break in future versions.

Refer to the Configuration guide for help with setting up your config.yaml file to the appropriate values.

Systemd Unit

Here is an example of a systemd unit file that you can use to manage the Headplane service:

[Unit]
Description=Headplane
# Decomment the following line if running on bare metal with integrated mode (/proc integration)
# PartOf=headscale.service

[Service]
Type=simple
User=headplane
Group=headplane
WorkingDirectory=/path/to/headplane
ExecStart=/usr/bin/node /path/to/headplane/build/server/index.js
Restart=always

[Install]
WantedBy=multi-user.target

You will need to replace /path/to/headplane with the actual path to the Headplane repository on your system. Save this file as headplane.service in /etc/systemd/system/ and run systemctl enable headplane to enable the service.

Other fields may also need some configuration, as this unit expects a user and a group called headplane to exist on the system. You can change these values to match your system's configuration.