Docker compose file for beginers

[johntucker]

Ir would be very helpful for those that are not knowledgeable with docker and are attempting to to learn headscale & tailscale to have a simpler docker compose file for headscale + headscale-admin.

The docker compose file with Traefik very much complicates the process unnecessarily and not every use case needs a reverse proxy. I'm not suggesting replacing the headscale + headscale-admin + traefik docker compose file but just adding the simpler version for those that are starting out.

[GoodiesHQ]

Fair enough! Truthfully, reverse proxies make life a lot easier because you have full control over the specific paths that are hosted at different endpoints (e.g. / -> headscale and /admin -> headscale-admin`) on the same URI. Without that, you need to handle CORS properly which I'm actually not certain can be done on the headscale side of things.

I also do not recommend running this or any web application without SSL. headscale-admin is just a list of static HTML + JS + CSS files at the end of the day, so serving it however you prefer is entirely up to you. SSL prevents attacks such as script injection, and I worry that a compose file that is TOO simple would lead to people running this over HTTP which I simply cannot recommend or support.

If there are perhaps other reverse proxies that you find simpler to use, I'm happy to try and replicate the setup on my end, but I wouldn't feel comfortable doing a bare bones container host with no SSL.

[Minxster]

@GoodiesHQ I fully understand and agree with what your saying. But I'm actually in the same boar as @johntucker, in that I'm no expert with these things, and having an example compose without the (needed for final dev or prod) reverse proxy information, would help me out.

I'm trying to just get some basic containers running without the reverse proxy elements. Just so I can understand the essentials of who is talking to what and how. From there I'd like to be use my existing Nginx Proxy Manager (NPM) for all the heavy lifting.

I'm chipping away at my test setup just now, but it's hard to figure out if I have a "me" (setup) error, or if there is something else wrong. It's the reason for me coming here TBH... In that the main GUI for admin loads but then only shows a settings button that does not work 🤷‍♂️

[johntucker]

I had held off on adding more but I have found that it is difficult to learn given the additional complexity that comes with each function (docker+headscale+headscale-ui+proxy....) Finding answers using google/youtube has it's own issues. Usually there is little to be gained from these sources if there are any deltas with the environment (different VPS, linux distro, dns provider, and on & on) This is compounded by the lack of background as to the decisions and rationale for the choices made. What I have discovered is that there is little more than the steps necessary to reimplement the exact situation. I acknowledge that there is an opportunity to learn from the failures but it also adds to the frustration.

My plan is to start over and implement traefik first as the proxy, getting that working with letsencrypt for TLS certs - routing to ngnix web service, adding headscale and then one of the headscale ui's.

If I can find a suitable place to document this journey. I will.

[Minxster]

Ok, so scratch what I posted before!... I went back to basics and just re-did my whole compose setup. I followed this https://www.youtube.com/watch?v=OECp6Pj2ihg by James Turland.

You need some of reverse proxy running before doing any of this. You can get headscale to run without it, but to use any of these admin/UI tools, you have to have one running. Fortunately for me, that was fine as I've been running one for ages. After that I just followed the video. By about 12mins in, I could confirm headscale was running (e.g. http://xx.xx.xx.xx/windows), then I could drop in my reverse proxy and confirm. Then I just added in the UI container(s). They'll need to use the SAME URL, so you don't get CORS issues, so you'll need to setup advanced proxy stuff to point "/admin/" to the different container/PORT.

Everything isn't working yet, but just starting from scratch helped. But you must get a reverse proxy running first.

[lbazmx]

Hi,

I got it working good using portainer to set up. Headscale and Headscale-Admin are defined in the stack that creates their respective containers while the nginx proxy manager (npm) stack defines and creates its container. I'll be happy to share my portainer stacks for both. In order to use Headscale-Admin you must have a reverse proxy working first.

:)

[GoodiesHQ]

@lbazmx that would be great! Would be cool to open a new issue or provide a gist with your setup. As mentioned in an earlier comment, I just can't in good conscience provide a method to host headscale-admin without SSL. I fear too many people would use it in production and that would lead to insecure setups vulnerable to static injection attacks. Anyone adept at dealing with docker would still be able to do it. You could run it on a different port or just place the static files in a served directory. It can be done, I just don't want to provide a method so easy that it would be insecure.

[lbazmx]

Hi,

I got it working good using portainer to set up. Headscale and Headscale-Admin are defined in the stack that creates their respective containers while the nginx proxy manager (npm) stack defines and creates its container. I'll be happy to share my portainer stacks for both. In order to use Headscale-Admin you must have a reverse proxy working first.

:)

Take into account that you must have a working docker install with portainer up and running. My docker runs in a linux host running debian 12.

You need to have your own domain name that you can edit dns on. You can either register one or get a free one whatever is best for you. I have my own paid domain but I also use dynv6.com which is free, it works with static and or dynamic ip addresses. This is because without a fqdn you cannot create ssl certificates with lets encrypt.

Read up on this to set it up. https://github.com/NginxProxyManager/nginx-proxy-manager

This is my stack for npm on portainer:

version: '3.0'

volumes:
  data:
  etc_letsencrypt:
services:
  npm:
    container_name: nginx_proxy_mgr
    image: 'jc21/nginx-proxy-manager:2.10.4'
    restart: always
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - /docker/npm/data:/data:rw
      - /docker/npm/etc_letsencrypt:/etc/letsencrypt:rw

---

once npm is working and you have set up your domain with your ssl certificate in npm we can continue.

Now we have to set up another stack for headscale and headscale-admin.

This is my stack for headscale and headscale-admin on portainer:

version: '3.7'
services:
  headscale:
    container_name: headscale
    volumes:
        - /docker/headscale/config:/etc/headscale/
        - /docker/headscale/keys:/var/lib/headscale/
    ports:
        - 8080:8080
        - 9090:9090
    image: headscale/headscale:0.23.0-alpha3
    command: headscale serve
    restart: always

  headscale-admin:
    image: goodieshq/headscale-admin:latest
    container_name: headscale-admin
    restart: always
    ports:
      - 8081:80 

---

After this you will have to create an apikey for headscale-admin to use for headscale.

This is a very general use case, please let me know if i need to try to clear up any steps.

@GoodiesHQ what do you tnink ?

[solisinvictum]

Thanks to @lbazmx for your stack of headscale and headscale-admin. I try it in few minutes out. Must first install the Host VM.

@GoodiesHQ: You are right about reverse proxies and ssl. But from my point of view, the delivered Compose file in this repo is even TOO easy. Why?:

Because:

Im running a Homelab, with a threadripper server, 128gb ram, yala yala. On it proxmox.

On proxmox im running everything in VM's. Invidious, searxng, nextcloud yala yala. Everything needs a SSL Cert and encryption. But i have only a home internet connection, so only 1 IP adress.

So i have a another VM, with nginx reverse proxy manager running on it. This VM is the only one who is accessable from the internet. This handles everything.

So what i need only to do, is to set up npm like that:

I want to have only headscale self accessable from the internet. the web ui not. because that i access only if im home from lan.

[lbazmx]

Hi,

You have to configure your npm proxy host instance custom location:

You also have to setup an access list on npm:

Hope this helps.

[Sinister646]

@lbazmx is the reason you only load settings because you dont create an access list ?