update docs

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

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 <target-host>
+    ```
+* 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 <headscale-server>
+    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