ernestoyoofi/headscale-ui repository overview

⁠Headscale UI

A lightweight web interface for managing your Headscale⁠ server, built with Go (Backend) and React (Frontend). It acts as a secure proxy to the Headscale API.

⁠✨ Features

• Node Management: List, register, remove, and rename nodes. Support for approving subnets/routes.
• User Control: Easily create, rename, and manage users (namespaces).
• Access Control (ACL): Built-in JSON editor to limit and control device access within your tailnet.
• Secure Backend: Simple authentication and JWT-based proxying to keep your Headscale API key safe.

⁠⚠️ Limitations

While this UI covers most daily operations, please keep the following in mind:

• CLI/File Access Required: Certain advanced configurations, such as DNS and Base Domain settings, cannot be managed via the Headscale API yet. You will still need access to the server's CLI or configuration files for these tasks.
• Docker-First Design: This project is optimized for Docker environments. Running it directly on a host machine is not officially supported or recommended at this time.

⁠🚀 Getting Started

⁠Prerequisites

• A Linux server.
• Docker & Docker Compose.
• An existing Headscale server and an API Key.
• Golang, Nodejs/Bun, C Compailer (If running on host machine)

⁠Installation via Docker

The easiest way to deploy Headscale UI is using Docker:

docker run -d \
  --name headscale-ui \
  -p 3050:3050 \
  -e HEADSCALE_SERVER="https://your-headscale-domain.com" \
  -e SERVER_LISTEN=":3050" \
  ernestoyoofi/headscale-ui:latest

⁠Host Environment (Not Recommend)

1. Clone the Repository

   git clone https://github.com/ernestoyoofi/headscale-ui.git
   cd headscale-ui
   

   Copy

   You need a golang, bun/nodejs and C to build this.

2. Build the Backend.

   cd backend
   go build -o headscaleui-host ./cmd/server
   chmod +x ./headscaleui-host
   sudo cp ./headscaleui-host /usr/local/bin/headscale-ui
   cd ..
   

   Copy

3. Build the frontend.

   Using Node.js/NPM:

   cd frontend
   npm install
   npm run build
   sudo mkdir -p /root/headscale-ui/app/
   sudo mkdir -p /var/www/headscale-ui
   sudo cp -r ./dist/* /var/www/headscale-ui/
   rm -r ./dist
   cd ..
   

   Copy

   Using Bun:

   cd frontend
   bun install
   bun run build
   sudo mkdir -p /root/headscale-ui/app/
   sudo mkdir -p /var/www/headscale-ui
   sudo cp -r ./dist/* /var/www/headscale-ui/
   rm -r ./dist
   cd ..
   

   Copy

4. Systemd Service Configuration

   Create a service file at /etc/systemd/system/headscale-ui.service:

   [Unit]
   Description=Headscale UI Service
   After=network.target
   
   [Service]
   Type=simple
   User=root
   WorkingDirectory=/var/lib/headscale-ui
   ExecStart=/usr/local/bin/headscale-ui
   Restart=on-failure
   RestartSec=2s
   
   # Environment Configurations
   Environment=SQLITE_LOCATION=/var/lib/headscale-ui/database.db
   Environment=UNJWT_SECRET=/var/lib/headscale-ui/jwt-token
   Environment=DIST_FRONTEND=/var/www/headscale-ui
   Environment=HEADSCALE_SERVER=http://localhost:8080
   Environment=SERVER_LISTEN=:3050
   
   [Install]
   WantedBy=multi-user.target
   

   Copy

5. Enable and Start Service

   sudo mkdir -p /var/lib/headscale-ui
   sudo systemctl daemon-reload
   sudo systemctl enable --now headscale-ui
   

   Copy

6. Access the dashboard via your IP or domain (Port 3050).

7. Complete the Admin Account setup on the first run.

8. Input your Headscale API Key in the settings menu.

⁠Docker Compose Setup

1. Add the headscale-ui service to your existing docker-compose.yml. You can see a full example here.⁠

   headscale_ui:
    image: ernestoyoofi/headscale-ui:latest
    container_name: headscale-ui
    restart: unless-stopped
    networks:
      - headscale
    volumes:
      - ${PWD}/headscale-ui/database:/app/database
      - ${PWD}/headscale-ui/secret:/app/secret
    environment:
      - JWT_SECRET="PleaseAddYourSecretJwtToken" # Jwt Token
      - SERVER_LISTEN=":3050" # Server Listening
      - HEADSCALE_SERVER="headscale:8080" # Headscale Service Network
    labels:
      # If Usage Traefik Proxy
      - "traefik.enable=true"
      - "traefik.http.routers.headscale-ui.rule=Host(`login.tailscale.yourdomain.com`)"
      - "traefik.http.routers.headscale-ui.entrypoints=websecure"
      - "traefik.http.routers.headscale-ui.tls.certresolver=cloudflare"
      - "traefik.http.services.headscale-ui.loadbalancer.server.port=3050"
   

   Copy

2. Run docker-compose up -d.

3. Access the dashboard via your configured domain or IP.

4. On the first run, set up your Admin Account (Username & Password).

5. Input your Headscale API Key in the settings menu to start managing your network.

⁠⚙️ Environment / Configuration

⁠🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.⁠

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

⁠📄 License

Distributed under the Apache 2.0. See LICENSE for more information⁠.