Any WEB UI planned?

[lion24]

Hi there,

First, very nice project 😊 Testing it right now and works rock solid.

Do you have any planned to integrate a Web UI like the Tailscale one?

I guess for that TLS would need to be enforce, but I guess this is doable.
The WebUI can talk to the backend API and automatically register new nodes one the user is logged in.

I think this would be very handy and provide an experience really close to what Tailscale is doing 😊

The UI itself should be fairly quick to create, it's more the interaction with the backend that could be challenging I guess.

Let me know what's your plan.

Kr.

[kradalby]

We are currently adding a HTTP API, so making this will become possible within a couple of releases.

That said I dont have any concrete plans to add a web ui other than "down the line".

My priorities are driven by my need and I might work on Terraform provider first. Of course if someone would be willing to sponsor the feature, then the priorities could shift.

[fdelucchijr]

We are currently adding an HTTP API, so making this will become possible within a couple of releases.

That said I don't have any concrete plans to add a web UI other than "down the line".

My priorities are driven by my need and I might work on Terraform provider first. Of course, if someone would be willing to sponsor the feature, then the priorities could shift.

I’m a Flutter(Android, iOS, Web) developer in my company (actually I’m because of funds and economy of the company a FullStack (the only) developer in a microservices backend and an event-driven mobile app 🤣). I'll be happy to sponsor this feature. If the UI is made in Flutter it can take less than a week (and can be exported as a Windows/macOS app), if prefer a proper web framework can take a little longer because of MVC and management of components.

[kradalby]

@fdelucchijr we would appreciate help. I have some concerns with using Flutter, which is mainly that it would mean that the current maintainers would have to learn a new language (Dart) and Flutter as a framework.

But I am happy to have a chat and be convinced :)

Other than that I would probably opt for Elm + TailwindCSS as that is what I know. I assume using something like Typescript + Vue would make it accessible for contributors.

[fdelucchijr]

@kradalby
I have been thinking about this since I wrote the previous message. Flutter Web is good for web apps, but I feel that for the classic control panel it doesn't make much sense, Is some sort of overpowered. At some point, I will make a control panel with flutter just to be able to control the headscale server from my cell phone or without exposing the WebGUI (LoL 🤣).

Elm looks super interesting! I would love to learn it, but it is true that with typescript there would be more flexibility for contributors.
Tailwind I think is a very good option, in combination with Vue it can be perfect to make maintenance and development easiest possible.

The following steps should understand which usecases should go into the screens, and make a mockup of the layout. (At this point we don't need to choose a language yet, nor the complete API, just understand what the webpage should cover)

Is the conversation on this topic ok here? or is it preferred by a special chat?

[cgrs]

What about just having a Web UI completely decoupled from the server? That way anyone who wants to have different UIs can develop them or use them on their own, being in Flutter, Elm or Vue.

[fdelucchijr]

Sounds good, but I think would make a lot more variable the development and if theres no "oficial" web gui gonna come up a lot of unmantained or incompatible versions of the same panel.

@kradalby Say is in development an api. I think with proper docs should be enough for anybody to make a external webgui, and adding a bool parameter to deactivate the internal is more like a'cherry on top (for my idea of a Flutter mobile app this would be awesome).

Obviously this isn't my choice, as implies a handful of definitions in the complete project approach.

Deploy a headscale container with all the components and other with just the server with a companion container for the webgui is something interesting for k8s, tho.

[kradalby]

The API might be available as beta and "subject to change" in the version after next. It will support OpenAPI so client code can be generated.

The API will open for anyone to make a WebUI, so @cgrs, feel free :)

I would assume that at some point we might include one, and having a collected effort might make more sense.

Also having everything in the same binary would be neat and easy to ship around.

[srdjanrosic]

Might be an unpopular opinion, or .. not..

... but, how about not making a web APP at all... and instead, just having the server render some simple html with current status to start with, ... and then maybe adding a few endpoints that can take form submissions to change things down the line.

By this I mean, how about just using go templates for showing a mix of current config and state, and having a few blue links and buttons scattered around to do some common things and move around, ... and relying on simple re-rendering of a page for any complicated UX transitions.

... how it looks can be prettied up well enough with some basic CSS, ... and you could even do things like show/hide and tabs using CSS, ... if that's where things go (spoiler, radio-buttons are mutually exclusive like tabs and can be made to look like so).

---

Reason I'm leaning toward this solution (over any of the javascript/typescript/wasm + framework-du-jour), is because I think:

a) majority of tailscale (by proxy headscale) users, myself included, would probably appreciate simplicity in their stack
b) we'd end up not fragmenting or burdening end users with different UIs that are a potential source of confusion / analysis-paralysis during adoption phase, and a potential support / maintenance burden or a distraction down the road.
c) requires very little no additional dependencies or toolchain changes
d) requires very little to no additional cognitive load to maintain / build / run .. and extend with new features, as they appear on the back end.

---

None of that would be necessarily exclusive to having a well thought out API as well ... but having the info laid out in a browser would be a bit more friendly to casual users (folks who don't manage VPNs for a living or as part of their critical role at a company or similar).

Security wise, beyond basic TLS, we'd probably be mostly good with just some basic cryptographic xsrf tokens stuffed in form fields and some explicit http headers (CSP, x-frame-options, that kind of stuff).... not sure how we'd think about identity in the web ui in the first place ... oauth?

---

development process wise - a good start would be to expose just the read-only status somehow safely, before allowing state mutations through the webui.

[bohtho]

I'm just a weekend code (w)hacker but am a Tailscale (UI/coordinator) user, and my 2p go to a decoupled UI as a simple but modern web gui (precompiled js please). How about something based on Svelte (or Svelte Kit) which is succinct and easy to grok for new developers? Then you smart lot can concentrate on the API and coordinator itself.

[klvnptr]

I suggest using some straightforward decoupled React +Tailwind UI. It is very popular and it is easier to recruit contributors :)

[fdelucchijr]

@kradalby, sorry because of my hiatus, the holidays have been a mess. There's news on the API progress? I've already made a Figma board and started a mood board of different self-hosted solutions to make a wireframe of the UI.

Seen that there's still a debate on how to implement the WebUI at a technical level, I will stick to the conceptual level for now. Probably will drop the Figma board here when I have some of the modules ready.

I will maintain my opinion in a Tailwind-Vue combo, and really don't care much about the coupling in the server-client, but I really think there's a need for a Headscale officially maintained WebUI that at least show the state of the service and allow the admin to configure some settings (the more the better). This will expand the project as the best self-hosted VPN solution for regular users out there.

[gedw99]

The Tailscale gui for iOS and android is built using gio

i used to use flutter and changed to gio because it’s golang and you don’t get road blocked for doing low level aspects as much as you do with flutter.

We could quite quickly build the web , task tray, desktop and mobile clients using gio I feel .

also because it’s golang it makes it easier because the frontend and backend are all in golang so the same team can work on both.

we can base on

https://github.com/tailscale/tailscale-android

they use https://github.com/tailscale/walk to build their windows desktop gui.

At the time gio was not mature enough for windows compile targets. That’s maybe why they did not use it. It definitely is now.

Gio uses the standard golang build tags to include OS specific golang code .

i have GRPC and GRPC-web working between a gio frontend and go backend too. It just uses a slight fork of the improbable GRPC lib to use a slightly different web socket lib that works with WASM ( which is what gio web builds as ).

using GRPC makes forward engineering happen and supports schema evolution so that if the API on the server changes the clients will not break at runtime . Use buf to manage GRPC and we are good !!

[kradalby]

@fdelucchijr I have not been working on this for a bit, had a break so no news atm.
I can see myself starting to play around with headscale in a bit, but not yet.

As for my opinion/decision towards WebUI:

I have decided that if I will work on it, be involved and do possibly a good batch of the work, I will write it in Elm + TailwindCSS (or something like F#/Fable).

The reasoning for this is that I am doing this project for fun, and if I am to enjoy doing this, I cannot use JavaScript/Typescript/Vue/React as I do not find it fun to work with. I do enjoy working with Elm.

I do not intend to mandate that the project is done in Elm, this is mostly to make it clear that if I start it, or am to contribute, that will be the language. If anyone feel strongly about choosing more mainstream tech, that is fine, but then they better start working on it before I get to it and uphold a good enough quality (whatever-that-means).

I have no timeline for when I will consider diving into this as I don't personally need a WebUI for headscale.

As for other implementation details, I think for a WebUI to be viable, it must be embedded in the binary and served without any extra setup. Luckily Go is reasonably good at this.

[endigma]

Is there an HTTP API planned? If there was one I'd make a webui.

[gedw99]

Is there a link to the Figma screens ?

would be great to have a look at it

[artemklevtsov]

@endigma HTTP API already introduced (see #204).

[endigma]

@endigma HTTP API already introduced (see #204).

docs for routes/payloads anywhere?

[artemklevtsov]

docs for routes/payloads anywhere?

May by here: https://github.com/juanfont/headscale/tree/main/gen/openapiv2/headscale/v1

[endigma]

Cool, I'm probably gonna make a webui then. will post updates when there's something to look at.

[artemklevtsov]

Also could be useful:

headscale/app.go

Lines 415 to 434 in 7349738

	router.GET(
	"/health",
	func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"healthy": "ok"}) },
	)
	router.GET("/key", h.KeyHandler)
	router.GET("/register", h.RegisterWebAPI)
	router.POST("/machine/:id/map", h.PollNetMapHandler)
	router.POST("/machine/:id", h.RegistrationHandler)
	router.GET("/oidc/register/:mkey", h.RegisterOIDC)
	router.GET("/oidc/callback", h.OIDCCallback)
	router.GET("/apple", h.AppleMobileConfig)
	router.GET("/apple/:platform", h.ApplePlatformConfig)
	router.GET("/swagger", SwaggerUI)
	router.GET("/swagger/v1/openapiv2.json", SwaggerAPIv1)
	api := router.Group("/api")
	api.Use(h.httpAuthenticationMiddleware)
	{
	api.Any("/v1/*any", gin.WrapF(grpcMux.ServeHTTP))
	}

[kradalby]

This is the relevant part: #234 (comment).

Before we set of in multiple different directions, what is your idea of what you would like to achieve with the UI @endigma ?

[endigma]

@kradalby

My plan is to re-implement what's in the official tailscale UI likely with Svelte/Tailwind or Pico. If the limitation is in endpoints I'd likely yield feature wise until they are completed. I don't have the time to really dig into learning the whole headscale codebase, but I can handle a front-end.

[kradalby]

ok, just be aware, the API is not stable, and we will change it a fair amount in the upcoming releases.

0.13.0-beta3 is the first release with the API available. But we already have plans to change it quite a bit based on #311.

It supports OpenAPI v2, so if you are planning to contribute it, find a code generator for the API so we get in all the consistency :)

[endigma]

I'll look into code generation, may be able to use swagger to generate a stub client.

[kradalby]

Sounds about right, OpenAPI is what swagger was renamed into. Feel free to reach out to me on Discord if you want to discuss something.

[fdelucchijr]

@kradalby

My plan is to re-implement what's in the official tailscale UI likely with Svelte/Tailwind or Pico. If the limitation is in endpoints I'd likely yield feature wise until they are completed. I don't have the time to really dig into learning the whole headscale codebase, but I can handle a front-end.

If you start a repo prease add me. Or if you gonna add a PR, mention me, I will happily help you.
I have had a complete JS to TS migration in the past 2 weeks but in the following time I will be fully able to help. I think my project in Figma gonna be saved until there's a usable UI so we can design with peace of mind and usage experience.
In the past few days, I add some ideas such as Netmaker's node view to the management screen.

[kradalby]

Actually, before we set out in many different directions, can we please take a step back and write up a proposal on design and requirements so we don't do double work and ensure it is maintainable?

A bit like #311

@endigma @fdelucchijr

[endigma]

@fdelucchijr @kradalby

I'm happy to tackle this solo as a separate project but if you want to be a part of it you can find my contact info on my website. Reach out and we can discuss working as a team.

One thing that's set in stone is it's definitely not going to be part of this repo, merging a full ts/js/svelte project into an existing go repo sounds like a nightmare.

I'm also in the discord under @endigma4426 if you don't have telegram.

[marie6324]

Following up on this to see if there's been any movement from anyone involved

[routerino]

Following up on this to see if there's been any movement from anyone involved

A sveltekit/tailwind based web UI is now available, can be found here.

Barring anyone else coming up with their own implementation, what needs to be asked now is the appetite to integrate (or not integrate) this web UI into headscale itself. Here's some considerations that need to be thought out before charging ahead:

(Programming) Language Considerations

There's a bit of talk in this whole thread about sticking to minimal raw HTML/CSS, which I initially tried with alpinejs and htmx. This concept was abandoned, as I (like most people) learned the hard way why all the popular frameworks are compiled javascript languages. Basic things like type checking (typescript), modular css (postcss), and scope management is nearly impossible in vanilla javascript, and makes any serious project quickly become spaghetti.

So the web ui is a mix of svelte-kit (framework), tailwind/daisyui (css) and typescript, compiled down to static html/js/css. This is a good middle ground with low dependencies and meeting the core requirement (being able to be hosted statically). Speaking of which:

Integration with Headscale

Right now it's a bit tricky to use the UI, as it needs to be hosted separately, and CORS needs injection if the hosting isn't on the same subdomain. The CORS issue is fixable, but anything further will depend on the headscale maintainer's appetite to integrate a separate project. So I can see three options with integration:

• No Integration at all
  • Just keeping it separate, the way it is. Makes it harder to host, but that way the two projects aren't interdependent on eachother. Being able to configure CORS (in the headscale 17.0 roadmap) will ease the pain here a bit, but it will still be too much of a hassle for the average person to figure out.
• Dynamic Integration
  • Have the headscale server be configurable to automatically host a "web" folder located in the same location as the binary. This is a good middle ground, the only additional requirement for installation being the need to extract the site to the same location as headscale. The site is entirely static and client driven so there's no particular permissions to worry about (well aside from a bad party messing with the files, but an intruder with that access has already pwned the environment).
• Full Integration
  • Embed the site into headscale's binary. This is by far the best experience for end users (no additional configuration required), but also the most intrusive to maintain. It would also mean headscale would have to package the site's builds with headscale directly.

Authentication

The current system saves an API key to the browser local storage, which isn't ideal, but works. Doing so can potentially be exploited by XSS, but XSS protections are in place with CSP enabled on build. It's a good enough solution, but eventually it would be nice if headscale could be an OIDC relying party for the site, same way it works with tailscale. How this will work with the app is something I haven't investigated and will probably need cooperation with the headscale maintainers if it's a wanted feature.

ACL management

ACL Management is a hard concept to gui-fy, but it's on my immediate radar. The big stopping block is that there is no way to update ACLs via the API, which will be required for this feature to exist. I can start some of that work, but it'll be a big task to manage.

Source code management

There were rumblings about putting the web source into the same repo, which I wouldn't necessarily recommend. If it was all static HTML/CSS/JS, that would be a strong possibility, but not for anything compiled. However if the headscale maintainers want to fork it, I can potentially move development off my own repo.

Thoughts? Many of these considerations need the headscale folks to be on board for implementation, so it's a question of how much they want to get tied to using this UI (if at all).

[ptman]

@iFargle don't sell yourself short. If you created that then you definitely are a programmer by any stretch.

[evenh]

@iFargle I'm agreeing heavily with @ptman here (it also looks really awesome). I would think that bringing the code to GitHub would make it easier for others to contribute. I see that @anjomro has started bringing down the container image size in his fork already 🎉

[iFargle]

Alright I think I've figured it out... I've moved the repo here:
https://github.com/iFargle/headscale-webui

I'm now mirroring it to my personal git instance instead of the other way around.
@anjomro - I've added some of your changes. I think I got them all? Now that it's on GitHub it should be easier to work together on this 👍

[kradalby]

This is what I was going (hoping) for when I added the API, specially since I didnt have any immediate plans to make a UI, and now loads of time later, we have some good alternatives.

I think realistically, I will not do any work on a UI in the foreseeable future and I suggest that we add a section to the README with links to the two pure UI alternatives here from @routerino and @iFargle.

@gps949, I would be open to linking yours too, but currently it is a fork and not a UI, would you consider changing that? And we need to mark them with language support.

PRs to add them to the readme will be welcomed.

[cloverzrg]

anybody wanna look at this? https://github.com/gps949/Mirage

前后端分离比较好, 把前端单独出来

[xrain0610]

I made a ui with Angluar 15, it is a static web, credit save in localstorage. https://github.com/simcu/headscale-ui

[gbraad]

I am working on two Cockpit applications; one for the Tailscale client state and management. The other is to manage Headscale for user, node and routes management.

• https://github.com/spotsnel/cockpit-tailscale (alpha stage)
• https://github.com/spotsnel/cockpit-headscale (scaffolding stage)

---

@kradalby the API is not the only way to interact, as with -o json it allows integration similarly as tailscale itself. How 'stable' are the data structures?

[strausmann]

Very cool

[loprima-l]

@kradalby Would you like this to be an actual PR ? I'm interested to build an effective UI but think that it should come as a part of headscale so the people doesn't use a lot of different UI and divide themselves on different projects.

[kradalby]

@loprima-l, the issue with having someone contribute a UI is the ongoing maintenance after its has been contributed. We are already far behind on all the things we need to support of regular features and bugs and having a second sizable codebase added to the project will be a large burden on us as maintainers.

I appreaciate that in an ideal world, the contributor of the "official" UI might have the intention or time to maintain it, but in reallity, the burden of making sure that new features are up to scratch with the UI will fall on us.

I'm currently very happy with the bring your own UI setup we have now as it does not cause us more maintainence and users have several to choose from.

[loprima-l]

I'm not interested to contribute in that way, the API would require some changes if I implemented an UI and i don't wanna break the others UI if there isn't any official one. Good luck with Headscale

[github-actions]

This issue is stale because it has been open for 90 days with no activity.

[sunjam]

Open please

[Arispex]

I made a web ui using React and Mantine UI. It can be hosted using any preferred web server, such as Caddy, Nginx, or Apache. https://github.com/Arispex/headscale-ui

[github-actions]

This issue is stale because it has been open for 90 days with no activity.

[juanfont]

Some years ago we took the decision of not developing a web UI for Headscale, but offer instead full HTTP/gRPC API for those 3rd party enthusiasts that wanted to develop their own.

We couldn't be happier with that decision. As of today, there are four web UIs listed in https://headscale.net/web-ui/, and several more can be found searching in GitHub https://github.com/search?q=headscale%20web&type=repositories.

If you are a developer of a web interface for Headscale and you want us to list your project in our website, please send a PR modifying https://github.com/juanfont/headscale/blob/main/docs/web-ui.md.

I am locking this thread for the time being.