starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 20:00:28 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

Quickstart script #447

New Issue
Closed
opened 2025-12-29 01:29:29 +01:00 by adam · 5 comments
adam commented 2025-12-29 01:29:29 +01:00
Owner
Copy Link

Originally created by @prom3theu5 on GitHub (Mar 20, 2023).

Headscale Quickstart script

Would it be beneficial to include quick start docker scripting that setups up a base instance of headscale, containerised along with headscale-ui, and expose them through Caddy?

I have one I use here: https://github.com/SimCubeLtd/headscale-quickstart, which when running will allow you to be setup in about 2 mins

It's interactive similar to the Netmaker quick-start, only it deploys 3 containers: Headscale, Headscale-ui and Caddy, and I massively prefer this project over netmaker.

Base config is UI and Headscale running on http, with them both exposed through Caddy which will setup TLS with a requested cert at startup (based on either the custom email address you add during the script execution that it will ask you for, or the random email address it automatically generates during install - This SSL cert comes from ZeroSSL, but it could come from lets encrypt too)

sudo wget -qO ./headscale-quickstart.sh https://raw.githubusercontent.com/SimCubeLtd/headscale-quickstart/main/headscale-quickstart.sh && sudo chmod +x ./headscale-quickstart.sh && sudo ./headscale-quickstart.sh

After running, you'd copy and past the create apikey command, and then paste that api key into the web dashboard settings page

Originally created by @prom3theu5 on GitHub (Mar 20, 2023). **Headscale Quickstart script** Would it be beneficial to include quick start docker scripting that setups up a base instance of headscale, containerised along with headscale-ui, and expose them through Caddy? I have one I use here: https://github.com/SimCubeLtd/headscale-quickstart, which when running will allow you to be setup in about 2 mins It's interactive similar to the [ Netmaker](https://github.com/gravitl/netmaker) quick-start, only it deploys 3 containers: Headscale, Headscale-ui and Caddy, and I massively prefer this project over netmaker. Base config is UI and Headscale running on http, with them both exposed through Caddy which will setup TLS with a requested cert at startup (based on either the custom email address you add during the script execution that it will ask you for, or the random email address it automatically generates during install - This SSL cert comes from ZeroSSL, but it could come from lets encrypt too) ```bash sudo wget -qO ./headscale-quickstart.sh https://raw.githubusercontent.com/SimCubeLtd/headscale-quickstart/main/headscale-quickstart.sh && sudo chmod +x ./headscale-quickstart.sh && sudo ./headscale-quickstart.sh ``` After running, you'd copy and past the create apikey command, and then paste that api key into the web dashboard settings page
adam added the enhancement label 2025-12-29 01:29:29 +01:00
adam closed this issue 2025-12-29 01:29:29 +01:00
adam commented 2025-12-29 01:29:30 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (May 10, 2023):

This is out of scope for this project, we do not support Docker or Reverse proxies (caddy).

@kradalby commented on GitHub (May 10, 2023): This is out of scope for this project, we do not support Docker or Reverse proxies (caddy).
adam commented 2025-12-29 01:29:30 +01:00
Author
Owner
Copy Link

@prom3theu5 commented on GitHub (May 10, 2023):

Strange as you have a k3s example lol
Not everyone wants to have a droplet running a k8s runtime

no drama :P

@prom3theu5 commented on GitHub (May 10, 2023): Strange as you have a k3s example lol Not everyone wants to have a droplet running a k8s runtime no drama :P
adam commented 2025-12-29 01:29:30 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (May 11, 2023):

Those examples are unsupported and community organised, but I agree, it was a week moment.

Happy for you to contribute your script to the unsupported section, but we often find that we end up supporting them, and we are therefore sceptical.

@kradalby commented on GitHub (May 11, 2023): Those examples are unsupported and community organised, but I agree, it was a week moment. Happy for you to contribute your script to the unsupported section, but we often find that we end up supporting them, and we are therefore sceptical.
adam commented 2025-12-29 01:29:31 +01:00
Author
Owner
Copy Link

@PizzaProgram commented on GitHub (Jun 17, 2023):

Get an API key:

After the script finished, an API key must be created to be able to log in from the UI.

  • The format is: docker exec <headscale container> headscale apikeys create -e <expire-interval>

So for this docker you need to run this line on the server to get one:

  • docker exec headscale headscale apikeys create -e 9999d
    (9999d = 27 years)

Additional infos:

  • This auto-install script is creating a docker for THIS UI . (Not the most-contributed one.)

  • You need to create both api.<yourdomain> and dashboard.<yourdomain> domains, because * wildcard may not work with your DNS provider

  • The ZeroSSL may not be able to create / process your SSL by Caddy, because it needs the ZeroSSL API Key, which you can get if you log in to zeroSSL Developer menu , copy and insert to caddyfile at: cert_issuer zerossl <your-API-key>

  • I've also added EAB too to make sure it works:

{
	cert_issuer zerossl <zero-ssl-api-key>
	# ZeroSSL account
	acme_ca https://acme.zerossl.com/v2/DV90
	email info@my-email-address.xyz
	acme_eab {
		key_id <zero-ssl-key_id>
		mac_key <zero-ssl-mac_key>
	}
}
@PizzaProgram commented on GitHub (Jun 17, 2023): # Get an API key: After the script finished, an API key must be created to be able to log in from the UI. - The format is: `docker exec <headscale container> headscale apikeys create -e <expire-interval>` So for this docker you need to run this line on the server to get one: - `docker exec headscale headscale apikeys create -e 9999d` _(9999d = 27 years)_ ## Additional infos: - This auto-install script is creating a docker for [THIS UI](https://github.com/gurucomputing/headscale-ui) . (Not the most-contributed one.) - You need to create both `api.<yourdomain>` and `dashboard.<yourdomain>` domains, because * wildcard may not work with your DNS provider - The ZeroSSL may not be able to create / process your SSL by Caddy, because it needs the `ZeroSSL API Key`, which you can get if you log in to [zeroSSL Developer menu](https://app.zerossl.com/developer) , copy and insert to caddyfile at: `cert_issuer zerossl <your-API-key>` - _I've also added EAB too to make sure it works:_ ```caddyfile { cert_issuer zerossl <zero-ssl-api-key> # ZeroSSL account acme_ca https://acme.zerossl.com/v2/DV90 email info@my-email-address.xyz acme_eab { key_id <zero-ssl-key_id> mac_key <zero-ssl-mac_key> } } ```
adam commented 2025-12-29 01:29:31 +01:00
Author
Owner
Copy Link

@PizzaProgram commented on GitHub (Jun 17, 2023):

Personal experience:

  • This script did everything in 1 minute !! AWESOME 👍
    (I've tried to install headscale + UI + Caddy and configure them manually for a week long before, but did not succeed.)

Recommendation for improvements:

  1. The script should ask for if not generating a random-domain.

  2. For me: the final "Headscale setup is now complete. ... " part did not show.
    (After showing "Testing Caddy setup (please be patient, this may take 1-2 minutes)" ... the script exited immediately) But it is working!

  3. Should call the docker exec headscale headscale apikeys create -e 9999d line itself to generate the necessary API key.

  4. Maybe the other UI would be better.

    • or both ? +1 docker would not hurt.
@PizzaProgram commented on GitHub (Jun 17, 2023): ### Personal experience: - This script did everything in 1 minute !! AWESOME 👍 _(I've tried to install headscale + UI + Caddy and configure them manually for a week long before, but did **not** succeed.)_ ### Recommendation for improvements: 1. The script should ask for <zero-ssl-api-key> if not generating a random-domain. 2. For me: the final "Headscale setup is now complete. ... " part did not show. (After showing "Testing Caddy setup (please be patient, this may take 1-2 minutes)" ... the script exited immediately) But it is working! 3. Should call the `docker exec headscale headscale apikeys create -e 9999d` line itself to generate the necessary API key. 4. Maybe[ the other UI](https://github.com/ifargle/headscale-webui) would be better. - or both ? +1 docker would not hurt.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#447
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?