mirror of
https://github.com/tale/headplane.git
synced 2026-10-26 06:30:12 +00:00
Aarnav Tale
79 lines
2.1 KiB
Plaintext
79 lines
2.1 KiB
Plaintext
---
|
|
title: Docker
|
|
description: Install Headplane with Docker.
|
|
---
|
|
|
|
# Docker
|
|
|
|
The Docker image is the recommended way to run Headplane. It includes the web
|
|
UI, the [agent](/features/agent) and the [Browser SSH](/features/ssh) module,
|
|
all prebuilt.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker with Docker Compose
|
|
- Headscale and a Headplane config file, as described in
|
|
[Before installing](/install#before-installing)
|
|
|
|
## Installation
|
|
|
|
Mount the config file and a directory for Headplane's own data, which holds
|
|
its database and the agent's state:
|
|
|
|
```yaml
|
|
services:
|
|
headplane:
|
|
image: ghcr.io/tale/headplane:latest
|
|
container_name: headplane
|
|
restart: unless-stopped
|
|
ports:
|
|
- "3000:3000"
|
|
volumes:
|
|
- "./config.yaml:/etc/headplane/config.yaml"
|
|
- "./headplane-data:/var/lib/headplane"
|
|
```
|
|
|
|
If Headscale runs in Docker too, put both containers on the same network and
|
|
point `headscale.url` at the container, for example `http://headscale:8080`.
|
|
|
|
Run `docker compose up -d`, then open `http://localhost:3000/admin`.
|
|
|
|
## Signing in
|
|
|
|
Until [SSO](/features/sso) or [proxy authentication](/features/proxy-auth) is
|
|
set up, sign in with a Headscale API key, created inside the Headscale
|
|
container:
|
|
|
|
```bash
|
|
docker exec headscale headscale apikeys create --expiration 90d
|
|
```
|
|
|
|
See [API keys](/configuration/api-keys) for how keys and sessions work.
|
|
|
|
## Health checks
|
|
|
|
The image has a built-in healthcheck, so `docker ps` reports whether Headplane
|
|
is up. It follows Headplane's port and TLS settings, and runs every 30 seconds
|
|
with a 5 second timeout and 3 retries. To change the timing, override it in the
|
|
compose file:
|
|
|
|
```yaml
|
|
services:
|
|
headplane:
|
|
healthcheck:
|
|
interval: 2m
|
|
```
|
|
|
|
## Debugging
|
|
|
|
The image has no shell. For one, switch to the matching `-shell` tag,
|
|
such as `ghcr.io/tale/headplane:latest-shell`. It's the same build on Alpine,
|
|
with `bash` and `curl`.
|
|
|
|
## Next steps
|
|
|
|
- To edit DNS and sign-in restrictions from the UI, set up the
|
|
[Docker integration](/configuration/integrations#docker).
|
|
- Put Headplane behind a [reverse proxy](/configuration/reverse-proxy).
|
|
- See [After installing](/install#after-installing) for the rest.
|