personal_infra/ansible/services/headscale/deploy_headscale_playbook.yml

- name: Deploy headscale and configure Caddy reverse proxy
  hosts: vpn_control
  become: no
  vars_files:
    - ./headscale_vars.yml
  vars:
    headscale_subdomain: "{{ subdomains.headscale }}"
    headscale_domain: "{{ headscale_subdomain }}.{{ root_domain }}"
    headscale_base_domain: "tailnet.{{ root_domain }}"

  tasks:
    - name: Install required packages
      become: yes
      apt:
        name:
          - wget
          - gnupg
        state: present
        update_cache: yes

    - name: Download headscale DEB package
      get_url:
        url: "https://github.com/juanfont/headscale/releases/download/v{{ headscale_version }}/headscale_{{ headscale_version }}_linux_amd64.deb"
        dest: /tmp/headscale.deb
        mode: '0644'

    - name: Install headscale package
      become: yes
      apt:
        deb: /tmp/headscale.deb
        state: present

    - name: Remove temporary DEB file
      file:
        path: /tmp/headscale.deb
        state: absent

    - name: Ensure headscale user exists
      become: yes
      user:
        name: headscale
        system: yes
        shell: /usr/sbin/nologin
        home: /var/lib/headscale
        create_home: yes
        state: present

    - name: Create headscale data directory
      become: yes
      file:
        path: /var/lib/headscale
        state: directory
        owner: headscale
        group: headscale
        mode: '0750'

    - name: Create headscale run directory
      become: yes
      file:
        path: /var/run/headscale
        state: directory
        owner: headscale
        group: headscale
        mode: '0770'

    - name: Ensure headscale user owns data directory
      become: yes
      file:
        path: /var/lib/headscale
        owner: headscale
        group: headscale
        recurse: yes
        mode: '0750'

    - name: Add counterweight user to headscale group
      become: yes
      user:
        name: counterweight
        groups: headscale
        append: yes

    # This used to write `{}` - an empty policy - over the real ACL, which was
    # maintained by hand on the box. It had already flattened it once
    # (/etc/headscale/acl.json.937464.2026-09-12@14:03:08~ is Ansible's own
    # backup of the 1596-byte policy it replaced), and every subsequent
    # site.yml run would have taken the whole tailnet's access rules with it.
    #
    # The policy now lives in templates/acl.json.j2, captured from the live
    # file on 2026-09-19. validate first: a malformed policy is one headscale
    # refuses to load, which is the same outage as an empty one.
    - name: Deploy the Headscale ACL policy
      become: yes
      ansible.builtin.template:
        src: acl.json.j2
        dest: /etc/headscale/acl.json
        owner: headscale
        group: headscale
        mode: '0640'
        validate: "python3 -m json.tool %s"
      notify: Restart headscale

    - name: Deploy headscale configuration file
      become: yes
      copy:
        dest: /etc/headscale/config.yaml
        content: |
          server_url: https://{{ headscale_domain }}
          listen_addr: 0.0.0.0:{{ headscale_port }}
          
          grpc_listen_addr: 0.0.0.0:{{ headscale_grpc_port }}
          grpc_allow_insecure: false
          
          private_key_path: /var/lib/headscale/private.key
          noise:
            private_key_path: /var/lib/headscale/noise_private.key
          
          prefixes:
            v4: 100.64.0.0/10
            v6: fd7a:115c:a1e0::/48
          
          derp:
            server:
              enabled: true
              region_id: 999
              region_code: "headscale"
              region_name: "Headscale Embedded DERP"
              verify_clients: true
              stun_listen_addr: "0.0.0.0:3478"
              private_key_path: /var/lib/headscale/derp_server_private.key
              automatically_add_embedded_derp_region: true
            urls:
              - https://controlplane.tailscale.com/derpmap/default
          
          database:
            type: sqlite3
            sqlite:
              path: /var/lib/headscale/db.sqlite
          
          unix_socket: /var/run/headscale/headscale.sock
          unix_socket_permission: "0770"
          
          log:
            level: info
            format: text
          
          policy:
            path: /etc/headscale/acl.json
          
          dns:
            base_domain: {{ headscale_base_domain | quote }}
            magic_dns: true
            search_domains:
              - {{ headscale_base_domain | quote }}
            nameservers:
              global:
                - 1.1.1.1
                - 1.0.0.1
        owner: root
        group: headscale
        mode: '0640'
      notify: Restart headscale

    - name: Test headscale configuration
      become: yes
      command: headscale configtest
      register: headscale_config_test
      failed_when: headscale_config_test.rc != 0

    - name: Display headscale config test results
      debug:
        msg: "{{ headscale_config_test.stdout }}"

    - name: Ensure headscale data directory has correct ownership before starting service
      become: yes
      file:
        path: /var/lib/headscale
        state: directory
        owner: headscale
        group: headscale
        mode: '0750'
        recurse: yes

    - name: Ensure headscale run directory has correct ownership
      become: yes
      file:
        path: /var/run/headscale
        state: directory
        owner: headscale
        group: headscale
        mode: '0770'

    - name: Enable and start headscale service
      become: yes
      systemd:
        name: headscale
        enabled: yes
        state: started
        daemon_reload: yes

    - name: Wait for headscale unix socket to be ready
      become: yes
      wait_for:
        path: /var/run/headscale/headscale.sock
        state: present
        timeout: 60
        delay: 2

    - name: Create headscale namespace if it doesn't exist
      become: yes
      command: headscale users create {{ headscale_namespace }}
      register: create_namespace_result
      failed_when: create_namespace_result.rc != 0 and 'already exists' not in create_namespace_result.stderr and 'UNIQUE constraint' not in create_namespace_result.stderr
      changed_when: create_namespace_result.rc == 0

    - name: Allow HTTPS through UFW
      become: yes
      ufw:
        rule: allow
        port: '443'
        proto: tcp

    - name: Allow HTTP through UFW (for Let's Encrypt)
      become: yes
      ufw:
        rule: allow
        port: '80'
        proto: tcp

    - name: Allow STUN through UFW (for DERP server)
      become: yes
      ufw:
        rule: allow
        port: '3478'
        proto: udp

    - name: Publish headscale through Caddy
      ansible.builtin.include_role:
        name: caddy_site
        # This play is become: no and elevates per task. `apply` is how an
        # include_role passes become down to the role's tasks - `become:` on
        # the include itself is rejected. The role's handler sets its own.
        apply:
          become: yes
      vars:
        caddy_site_name: headscale
        caddy_site_domain: "{{ headscale_domain }}"
        # Raw body, and it must stay raw: the /admin* route in front of
        # Headplane is not expressible as a plain reverse_proxy. The previous
        # version of this task wrote only `reverse_proxy localhost:8080`, which
        # would have deleted the admin route and its auth on the next run.
        caddy_site_body: |
          @headplane {
              path /admin*
          }
          handle @headplane {
              basicauth {
                  {{ headscale_ui_username }} {{ headscale_ui_password_hash }}
              }
              reverse_proxy http://localhost:{{ headplane_port }}
          }
          # Headscale API is protected by its own API key authentication
          # All API operations require a valid Bearer token in the Authorization header
          reverse_proxy * http://localhost:{{ headscale_port }}

  handlers:
    - name: Restart headscale
      become: yes
      systemd:
        name: headscale
        state: restarted