DockerCopy Anchor Link

The Docker image is the recommended way to run Northplane. It includes the web UI, the agent and the Browser SSH module, all prebuilt.

PrerequisitesCopy Anchor Link

• Docker with Docker Compose
• Headscale and a Northplane config file, as described in Before installing

InstallationCopy Anchor Link

Mount the config file and a directory for Northplane's own data, which holds its database and the agent's state:

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 inCopy Anchor Link

Until SSO or proxy authentication is set up, sign in with a Headscale API key, created inside the Headscale container:

docker exec headscale headscale apikeys create --expiration 90d

See API keys for how keys and sessions work.

Health checksCopy Anchor Link

The image has a built-in healthcheck, so docker ps reports whether Northplane is up. It follows Northplane'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:

services:
  headplane:
    healthcheck:
      interval: 2m

DebuggingCopy Anchor Link

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 stepsCopy Anchor Link

• To edit DNS and sign-in restrictions from the UI, set up the Docker integration.
• Put Northplane behind a reverse proxy.
• See After installing for the rest.