Limited Mode

WARNING

Limited Mode is not recommended for production use. Please consider using one of the other installation methods for a production deployment. Limited mode lacks advanced features such as network management, remote web SSH, and more.

Limited Mode is good for users who want to test out the basic functionality provided by Headtower. It only interacts with the Headtower API and lacks all advanced features, making it suitable for local testing and development.

Prerequisites

• Docker (and optionally Docker Compose)
• Headscale version 0.27.0 or later installed and running
• A completed configuration file for Headtower.

Installation

TIP

If you want to test Limited Mode without Docker, you can follow the Native Mode installation guide and simply avoid setting up any of the advanced features.

Running Headtower in Limited Mode is as simple as running 1 command:

docker run -d \
    -p 3000:3000 \
    -v /path/to/your/config.yaml:/etc/headtower/config.yaml \
    -v /path/to/data/storage:/var/lib/headtower \
    --name headtower
    --restart unless-stopped
    ghcr.io/rnihesh/headtower:latest

It's important to mount your configuration file and also provide a persistent storage location for Headtower to store its own data. You can also change the port mapping if you want to run it on a different port.

Optional: Docker Compose

If you prefer using Docker Compose, here is a minimal example of a compose.yaml file that runs Headtower in Limited Mode:

services:
  headtower:
    image: ghcr.io/rnihesh/headtower:latest
    container_name: headtower
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - "/path/to/your/config.yaml:/etc/headtower/config.yaml"
      - "/path/to/data/storage:/var/lib/headtower"

Accessing Headtower

After starting the container, you can access the Headtower web interface by navigating to http://localhost:3000/admin in your web browser (replace localhost with your server's IP address or domain name if not running locally).

In order to log in, you'll need to supply a Headscale API key. You can create one by running the following command within your Headscale environment:

# You may want to tweak the expiration duration as needed
headscale apikeys create --expiration 90d

Limited Mode is intended for testing and development purposes, so please avoid using it in a production environment. For production deployments, consider using one of the other installation methods that will provide both the advanced features of Headtower and a more robust deployment.

Limited Mode also technically supports Single Sign-On (SSO) authentication, but some parts of it may not work as expected. For a full-featured experience with SSO, please use one of the other installation methods.