Skip to content

Latest commit

 

History

History
89 lines (75 loc) · 3.68 KB

Docker.md

File metadata and controls

89 lines (75 loc) · 3.68 KB

Docker Integration

The Docker integration allows you to run Headplane and Headscale separately in a dockerized environment. It allows you to unlock full functionality such as automatic reloading of ACLs, DNS management, and Headscale configuration management.

Deployment

When running with the Docker integration, it's assumed that both Headscale and Headplane will run as containers. If you are running Headscale natively, then refer to the Native Integration guide.

To enable the Docker integration, set the HEADSCALE_INTEGRATION environment variable to docker. You'll also need to supply HEADSCALE_CONTAINER with the name or ID of the Headscale container.

By default Headplane uses unix:///var/run/docker.sock to connect to Docker. This can be overridden by setting the DOCKER_SOCK environment variable. For example, a remote socket would be tcp://<my-remote-host>:2375. When setting the variable, you'll need to specify the protocol (unix:// or tcp://).

The DOCKER_SOCK variable does not support the HTTPS protocol.

To enable the Docker integration, set HEADSCALE_INTEGRATION=docker in the environment variables. Additionally, you'll need to pass in the HEADSCALE_CONTAINER environment variable. This should be either the name or ID of the Headscale container (you can retrieve this using docker ps). If the other integrations aren't setup, then Headplane will automatically disable the Docker integration.

By default the integration will check for /var/run/docker.sock, however you can override this by setting the DOCKER_SOCK environment variable if you use a different configuration than the default. When setting DOCKER_SOCK, you'll need to include the protocol (e.g., unix:// or tcp://). Headplane currently does not support the HTTPS protocol for the Docker socket.

Here's an example deployment using Docker Compose (recommended). Keep in mind that you'll NEED to setup a reverse proxy and this is incomplete:

services:
  headscale:
    image: 'headscale/headscale:0.23.0'
    container_name: 'headscale'
    restart: 'unless-stopped'
    command: 'serve'
    volumes:
      - './data:/var/lib/headscale'
      - './configs:/etc/headscale'
    ports:
      - '8080:8080'
    environment:
      TZ: 'America/New_York'
  headplane:
    container_name: headplane
    image: ghcr.io/tale/headplane:0.3.9
    restart: unless-stopped
    volumes:
      - './data:/var/lib/headscale'
      - './configs:/etc/headscale'
      - '/var/run/docker.sock:/var/run/docker.sock:ro'
    ports:
      - '3000:3000'
    environment:
      # This is always required for Headplane to work
      COOKIE_SECRET: 'abcdefghijklmnopqrstuvwxyz'

      HEADSCALE_INTEGRATION: 'docker'
      HEADSCALE_CONTAINER: 'headscale'
      DISABLE_API_KEY_LOGIN: 'true'
      HOST: '0.0.0.0'
      PORT: '3000'
        
      # Only set this to false if you aren't behind a reverse proxy
      COOKIE_SECURE: 'false'

      # Overrides the configuration file values if they are set in config.yaml
      # If you want to share the same OIDC configuration you do not need this
      OIDC_CLIENT_ID: 'headscale'
      OIDC_ISSUER: 'https://sso.example.com'
      OIDC_CLIENT_SECRET: 'super_secret_client_secret'

      # This NEEDS to be set with OIDC, regardless of what's in the config
      # This needs to be a very long-lived (999 day) API key used to create
      # shorter ones for OIDC and allow the OIDC functionality to work
      ROOT_API_KEY: 'abcdefghijklmnopqrstuvwxyz'

For a breakdown of each configuration variable, please refer to the Configuration guide. It explains what each variable does, how to configure them, and what the default values are.