mirror of
https://github.com/tale/headplane.git
synced 2026-10-27 06:57:53 +00:00
Aarnav Tale
118 lines
3.0 KiB
Plaintext
118 lines
3.0 KiB
Plaintext
---
|
|
title: Native
|
|
description: Build and run Headplane directly on a Linux host.
|
|
---
|
|
|
|
import { versions } from "@/lib/versions";
|
|
|
|
# Native
|
|
|
|
Headplane can run straight on the host, which suits setups where Headscale
|
|
already runs there, usually under systemd. It's built from source once, then
|
|
runs on Node.js.
|
|
|
|
## Prerequisites
|
|
|
|
- Linux
|
|
- Headscale and a Headplane config file, as described in
|
|
[Before installing](/install#before-installing)
|
|
- To build: Go matching the `go` directive in `go.mod`, and pnpm{" "}
|
|
<code>{versions.pnpm}</code>
|
|
- To run: Node.js <code>{versions.node}</code>
|
|
|
|
Go and pnpm are only needed to build. The result runs on Node.js alone.
|
|
|
|
## Building
|
|
|
|
```bash
|
|
# Optionally check out a release tag first
|
|
git clone https://github.com/tale/headplane.git
|
|
cd headplane
|
|
./build.sh
|
|
```
|
|
|
|
`build.sh` installs locked dependencies and builds the web UI, the Browser SSH
|
|
module, the [agent](/features/agent) and the healthcheck binary. The agent
|
|
lands in `build/hp_agent`. Copy it to `/usr/libexec/headplane/agent` to
|
|
use it, or see [the agent page](/features/agent#turning-it-on)
|
|
for another location.
|
|
|
|
## Running
|
|
|
|
Create the data directory from `server.data_path` (`/var/lib/headplane` by
|
|
default) and make it writable by the user that runs Headplane:
|
|
|
|
```bash
|
|
sudo mkdir -p /var/lib/headplane
|
|
sudo chown -R headplane:headplane /var/lib/headplane
|
|
```
|
|
|
|
Then start Headplane from the repository directory, so it can find `build/`:
|
|
|
|
```bash
|
|
node build/server/index.js
|
|
```
|
|
|
|
It reads `/etc/headplane/config.yaml` unless `HEADPLANE_CONFIG_PATH` points
|
|
elsewhere. Open `http://localhost:3000/admin` once it's up.
|
|
|
|
### systemd
|
|
|
|
Save this as `/etc/systemd/system/headplane.service`, adjusting the user and
|
|
paths, then run `sudo systemctl daemon-reload` and
|
|
`sudo systemctl enable --now headplane`:
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=Headplane
|
|
# Use headscale.service here instead if Headscale runs under systemd
|
|
After=network.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=headplane
|
|
WorkingDirectory=/opt/headplane
|
|
ExecStart=/usr/bin/node /opt/headplane/build/server/index.js
|
|
Restart=on-failure
|
|
RestartSec=5s
|
|
# Environment=HEADPLANE_CONFIG_PATH=/path/to/config.yaml
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
## Signing in
|
|
|
|
Until [SSO](/features/sso) or [proxy authentication](/features/proxy-auth) is
|
|
set up, sign in with a Headscale API key:
|
|
|
|
```bash
|
|
headscale apikeys create --expiration 90d
|
|
```
|
|
|
|
See [API keys](/configuration/api-keys) for how keys and sessions work.
|
|
|
|
## Custom path prefix
|
|
|
|
:::warning
|
|
`/admin` is the only supported prefix. Other prefixes aren't tested and may
|
|
break.
|
|
:::
|
|
|
|
The prefix is fixed at build time. To serve Headplane somewhere else, such as
|
|
`/headplane`, build it with `__INTERNAL_PREFIX`:
|
|
|
|
```bash
|
|
__INTERNAL_PREFIX=/headplane ./build.sh
|
|
```
|
|
|
|
Changing it again means rebuilding, and the reverse proxy has to route the new
|
|
path.
|
|
|
|
## Next steps
|
|
|
|
- To edit DNS and sign-in restrictions from the UI, set up the
|
|
[proc integration](/configuration/integrations#proc).
|
|
- Put Headplane behind a [reverse proxy](/configuration/reverse-proxy).
|
|
- See [After installing](/install#after-installing) for the rest.
|