Skip to content

Conversation

@lujian0571
Copy link

@lujian0571 lujian0571 commented Dec 22, 2025

Serve built-in web UIs directly from headscale

This change allows headscale to serve built-in static web interfaces
(e.g. admin or console UIs) directly from the headscale process.

By embedding and serving web assets internally:

  • Avoids deploying and maintaining separate web services
  • Eliminates the need for additional reverse proxy configuration
  • Reuses headscale’s existing HTTPS and certificate management
  • Simplifies authentication, routing, and operational complexity

This makes it easier to add and maintain management UIs while keeping
deployment minimal and self-contained.

  • have read the CONTRIBUTING.md file
  • raised a GitHub issue or discussed it on the projects chat beforehand
  • added unit tests
  • added integration tests
  • updated documentation if needed
  • updated CHANGELOG.md

- Introduce web config to enable and configure static file serving
- Implement RegisterWebApps to register configured web apps
- Add fileHandler for serving files, supporting directory index and SPA fallback
- Set default web config to disabled
- Define WebConfig and WebAppConfig structs
- Integrate web app registration into router
- Include unit tests covering various file handling scenarios
- Update config examples with web UI instructions
- Add missing `apps` layer under `web` for multiple web apps
- Consolidate SPA and non-SPA scenarios in a single table-driven test
- Cover directory access with and without index.html
- Include access to files under root and subdirectories
- Ensure URL path prefix is handled correctly
- Document default 301 redirect behavior for /*/index.html access
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant