From 3b88e6c5e8c7f2e45b7f81575496a88f6da23e19 Mon Sep 17 00:00:00 2001 From: counterweight Date: Mon, 3 Nov 2025 16:55:01 +0100 Subject: [PATCH] update docs --- 01_infra_setup.md | 5 ++++- 02_vps_core_services_setup.md | 30 ++++++++++++++++++++---------- 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/01_infra_setup.md b/01_infra_setup.md index e4353b2..d3ec566 100644 --- a/01_infra_setup.md +++ b/01_infra_setup.md @@ -27,7 +27,10 @@ This describes how to prepare each machine before deploying services on them. + Runs Debian 12 bookworm. + Has a public IP4 and starts out with SSH listening on port 22. + Boots with one of your SSH keys already authorized. If this is not the case, you'll have to manually drop the pubkey there before using the playbooks. -* You will need two VPSs: one to host most services, and another tiny one to monitor Uptime. We use two to prevent the monitoring service from falling down with the main machine. +* You will need three VPSs: + + One to host most services, + + Another tiny one to monitor Uptime. We use a different one to prevent the monitoring service from falling down with the main machine. + + A final one to run the headscale server, since the main VPS needs to be part of the mesh network and can't do so while also running the coordination server. * Move on once your VPSs are running and satisfies the prerequisites. ### Prepare Ansible vars diff --git a/02_vps_core_services_setup.md b/02_vps_core_services_setup.md index a005caa..1c4b708 100644 --- a/02_vps_core_services_setup.md +++ b/02_vps_core_services_setup.md @@ -237,20 +237,30 @@ Headscale is a self-hosted Tailscale control server that allows you to create yo ### Configure * **Network Security**: The network starts with a deny-all policy - no devices can communicate with each other until you explicitly configure ACL rules in `/etc/headscale/acl.json`. -* After deployment, you need to create a namespace and generate pre-auth keys for your devices. -* SSH into your VPS and run the following commands: - ```bash - # Create a namespace - headscale user create counter-net - - # Generate a pre-auth key for device registration - headscale preauthkeys create --user 1 # Assumes you've only created one user - ``` -* Copy the generated pre-auth key - you'll need it to register your devices. +* After deployment, the namespace specified in `services/headscale/headscale_vars.yml` is automatically created. ### Connect devices +#### Automated method (for servers reachable via SSH from lapy) + +* Use the Ansible playbook to automatically join machines to the mesh: + ```bash + ansible-playbook -i inventory.ini infra/920_join_headscale_mesh.yml --limit + ``` +* The playbook will: + * Generate an ephemeral pre-auth key (expires in 1 minute) by SSHing from lapy to the headscale server + * Install Tailscale on the target machine + * Configure Tailscale to connect to your headscale server + * Enable magic DNS so devices can talk to each other by hostname + +#### Manual method (for mobile apps, desktop clients, etc.) + * Install Tailscale on your devices (mobile apps, desktop clients, etc.). +* Generate a pre-auth key by SSHing into your headscale server: + ```bash + ssh + sudo headscale preauthkeys create --user counter-net --reusable + ``` * Instead of using the default Tailscale login, use your headscale server: * Server URL: `https://headscale.contrapeso.xyz` (or your configured domain) * Use the pre-auth key you generated above