Skip to content

Latest commit

 

History

History
69 lines (52 loc) · 2.67 KB

Native.md

File metadata and controls

69 lines (52 loc) · 2.67 KB

Native Integration

The Native integration allows you to run both Headplane and Headscale on bare-metal servers or virtual machines. This integration is best suited for environments where Docker or Kubernetes are not available or not desired.

Currently the Native integration only supports automatic reloading of ACLs. It cannot handle configuration changes as killing the headscale process can lead to undefined behavior or the service not restarting.

Deployment

  1. Follow the instructions to install Headscale from the Linux Installation Guide.

  2. Install Node.js version 20 or higher (your package manager most likely already has this).

  3. Install PNPM. This is required as Headplane has issues running correctly when installed and built via NPM or Yarn.

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

git clone https://github.com/tale/headplane # (or clone via SSH)
cd headplane
pnpm install
pnpm build

Running Headplane

Start Headplane with node build/headplane/server.js.

Headplane does need various environment variables to run correctly. The required variables can be found in the Configuration guide. If you choose to do this with a .env file, you can use the LOAD_ENV_FILE variable to tell Headplane to load the file.

Finally, make sure to set HEADSCALE_INTEGRATION=proc to take advantage of controlling Headscale natively on Linux.

LOAD_ENV_FILE=true node ./build/headplane/server.js

If you'd like, you can turn this into a systemd unit to manage the service. I plan to provide packages and unit files to make this easier in the future.

Cannot find ./build directory?

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. If you would like to keep the build directory in a different location, you can set the BUILD_PATH environment variable to the path of the build directory at runtime.

LOAD_ENV_FILE=true BUILD_PATH=/path/to/build node ./build/headplane/server.js

Changing Headplane's Path from /admin

Additionally, because you are building Headplane from source, you're able to change the default path that Headplane is served from. This can be done by specifying the __INTERNAL_PREFIX environment variable, when building.

__INTERNAL_PREFIX=/my-admin-path pnpm build

Keep in mind that this is very much an experimental feature. Things can easily break and until it's more stable, it's not recommended to use in production.