diff --git a/docs/Running.md b/docs/Running.md index dbb8704c..b784aba9 100644 --- a/docs/Running.md +++ b/docs/Running.md @@ -1,5 +1,6 @@ # Running headscale +## Server configuration 1. Download the headscale binary https://github.com/juanfont/headscale/releases, and place it somewhere in your $PATH or use the docker container ```shell @@ -12,8 +13,15 @@ docker pull ghrc.io/juanfont/headscale:x.x.x ``` --> -2. (Optional, you can also use SQLite) Get yourself a PostgreSQL DB running +2. When running headscale in a docker container, prepare a directory to hold all configuration + ```shell + mkdir config + ``` + +3. Get yourself a DB + + a) Get a Postgres DB running in docker ```shell docker run --name headscale \ -e POSTGRES_DB=headscale @@ -22,16 +30,22 @@ -p 5432:5432 \ -d postgres ``` - -3. Create a WireGuard private key and headscale configuration - + or b) Prepare a SQLite DB file ```shell - wg genkey > private.key - - cp config.yaml.example config.yaml + touch config/db.sqlite ``` -4. Create a namespace +4. Create a WireGuard private key, headscale configuration, and a DERP map file. Refer to [tailscale sample](https://raw.githubusercontent.com/tailscale/tailscale/main/net/dnsfallback/dns-fallback-servers.json) for more guidance. + + ```shell + wg genkey > config/private.key + + cp config.yaml.[sqlite|postgres].example config/config.yaml + + cp derp-example.yaml config/derp.yaml + ``` + +5. Create a namespace ```shell headscale namespaces create myfirstnamespace @@ -39,15 +53,9 @@ or docker: - the db.sqlite mount is only needed if you use sqlite - ```shell - touch db.sqlite docker run \ - -v $(pwd)/private.key:/private.key \ - -v $(pwd)/config.json:/config.json \ - -v $(pwd)/derp.yaml:/derp.yaml \ - -v $(pwd)/db.sqlite:/db.sqlite \ + -v $(pwd)/config:/etc/headscale/ \ -p 127.0.0.1:8080:8080 \ headscale/headscale:x.x.x \ headscale namespaces create myfirstnamespace @@ -56,10 +64,10 @@ or if your server is already running in docker: ```shell - docker exec headscale create myfirstnamespace + docker exec headscale namespaces create myfirstnamespace ``` -5. Run the server +6. Run the server ```shell headscale serve @@ -67,44 +75,38 @@ or docker: - the db.sqlite mount is only needed if you use sqlite - ```shell docker run \ - -v $(pwd)/private.key:/private.key \ - -v $(pwd)/config.json:/config.json \ - -v $(pwd)/derp.yaml:/derp.yaml \ - -v $(pwd)/db.sqlite:/db.sqlite \ + -v $(pwd)/config:/etc/headscale/ \ -p 127.0.0.1:8080:8080 \ headscale/headscale:x.x.x headscale serve ``` +## Nodes configuration -6. If you used tailscale.com before in your nodes, make sure you clear the tailscaled data folder +If you used tailscale.com before in your nodes, make sure you clear the tailscaled data folder ```shell systemctl stop tailscaled rm -fr /var/lib/tailscale systemctl start tailscaled ``` - -7. Add your first machine +### Adding node based on MACHINEKEY +1. Add your first machine ```shell tailscale up --login-server YOUR_HEADSCALE_URL ``` -8. Navigate to the URL you will get with `tailscale up`, where you'll find your machine key. +2. Navigate to the URL returned by `tailscale up`, where you'll find your machine key. -9. In the server, register your machine to a namespace with the CLI +3. In the server, register your machine to a namespace with the CLI ```shell headscale -n myfirstnamespace nodes register -k YOURMACHINEKEY ``` or docker: ```shell docker run \ - -v $(pwd)/private.key:/private.key \ - -v $(pwd)/config.json:/config.json \ - -v $(pwd)/derp.yaml:/derp.yaml \ + -v $(pwd)/config:/etc/headscale/ \ headscale/headscale:x.x.x \ headscale -n myfirstnamespace nodes register -k YOURMACHINEKEY ``` @@ -113,7 +115,7 @@ docker exec headscale -n myfirstnamespace nodes register -k YOURMACHINEKEY ``` -Alternatively, you can use Auth Keys to register your machines: +### Alternative: adding node with AUTHKEY 1. Create an authkey @@ -125,10 +127,7 @@ Alternatively, you can use Auth Keys to register your machines: ```shell docker run \ - -v $(pwd)/private.key:/private.key \ - -v $(pwd)/config.json:/config.json \ - -v$(pwd)/derp.yaml:/derp.yaml \ - -v $(pwd)/db.sqlite:/db.sqlite \ + -v $(pwd)/config:/etc/headscale/ \ headscale/headscale:x.x.x \ headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h ``` @@ -139,7 +138,7 @@ Alternatively, you can use Auth Keys to register your machines: docker exec headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h ``` -2. Use the authkey from your machine to register it +2. Use the authkey on your node to register it ```shell tailscale up --login-server YOUR_HEADSCALE_URL --authkey YOURAUTHKEY ```