headscale/handbuch.md

# Wiederherstellungs-Handbuch: Headscale in Google Cloud (Free Tier)
Dieses Handbuch enthält alle bereinigten Schritte und Konfigurationen, um Ihr Headscale-Setup auf der Domain `netz.wralto.org` im Projekt `rcloneprojekt` jederzeit fehlerfrei neu aufzusetzen.

---

## Teil 1: Google Cloud Infrastruktur (Cloud Shell)

Führen Sie diese Befehle in der **Google Cloud Shell** aus:

```bash
# 1. Standard-Netzwerk erstellen (falls gelöscht)
gcloud compute networks create default --project="rcloneprojekt" --subnet-mode=auto

# 2. Firewall-Regeln anlegen
gcloud compute firewall-rules create allow-http \
    --project="rcloneprojekt" --network=default --allow=tcp:80 --target-tags=http-server

gcloud compute firewall-rules create allow-https \
    --project="rcloneprojekt" --network=default --allow=tcp:443 --target-tags=https-server

gcloud compute firewall-rules create allow-ssh-iap \
    --project="rcloneprojekt" --network=default --allow=tcp:22 --source-ranges=35.235.240.0/20

gcloud compute firewall-rules create allow-headscale-stun \
    --project="rcloneprojekt" --network=default --allow=udp:3478

# 3. Die Gratis-VM erstellen (Optimiert für Free Tier)
gcloud compute instances create headscale-free-vm \
    --project="rcloneprojekt" \
    --zone="us-central1-a" \
    --machine-type="e2-micro" \
    --network-interface="network=default,network-tier=STANDARD" \
    --metadata="startup-script=sudo apt-get update && sudo apt-get install -y docker.io docker-compose" \
    --maintenance-policy="MIGRATE" \
    --provisioning-model="STANDARD" \
    --tags="http-server,https-server" \
    --create-disk="auto-delete=yes,boot=yes,device-name=headscale-free-vm,image=projects/debian-cloud/global/images/family/debian-12,mode=rw,size=30,type=projects/rcloneprojekt/zones/us-central1-a/diskTypes/pd-standard"
```
*Wichtig: Nach Erstellung die `EXTERNAL_IP` auslesen und beim Domain-Anbieter den A-Record für `netz.wralto.org` auf diese IP setzen.*

---

## Teil 2: Konfiguration auf der VM (Per SSH eingeloggt)

Verbinden Sie sich per **"SSH"-Button** mit der VM und führen Sie folgende Befehle aus:

```bash
# 1. Ordnerstruktur vorbereiten
mkdir -p ~/headscale/config ~/headscale/data ~/caddy
touch ~/headscale/config/config.yaml ~/headscale/data/db.sqlite ~/caddy/Caddyfile
```

### 2. Caddyfile befüllen
```bash
nano ~/caddy/Caddyfile
```
Inhalt einfügen:
```text
netz.wralto.org {
    reverse_proxy headscale:8080
}
```

### 3. Headscale config.yaml befüllen
```bash
nano ~/headscale/config/config.yaml
```
Inhalt einfügen (Syntax für v0.29.3+):
```yaml
server_url: https://netz.wralto.org
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 127.0.0.1:9090

prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48

database:
  type: sqlite3
  sqlite:
    path: /var/lib/headscale/db.sqlite

private_key_path: /var/lib/headscale/private.key
noise:
  private_key_path: /var/lib/headscale/noise_private.key

tls_cert_path: ""
tls_key_path: ""

dns:
  magic_dns: true
  base_domain: headscale.net
  nameservers:
    global:
      - 1.1.1.1
      - 8.8.8.8
  search_domains: []
  extra_records: []

logtail:
  enabled: false

derp:
  server:
    enabled: true
    region_id: 999
    region_code: "headscale-free"
    region_name: "Google Cloud Free Relais"
    stun_listen_addr: "0.0.0.0:3478"
    private_key_path: /var/lib/headscale/derp_server_private.key
  urls: []
  paths: []
  auto_update_enabled: false
```

### 4. Docker Compose Datei befüllen
```bash
nano ~/docker-compose.yml
```
Inhalt einfügen:
```yaml
version: '3.8'

services:
  headscale:
    image: headscale/headscale:latest
    container_name: headscale
    ports:
      - "3478:3478/udp"
    volumes:
      - ./headscale/config:/etc/headscale
      - ./headscale/data:/var/lib/headscale
    command: serve
    restart: unless-stopped

  caddy:
    image: caddy:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - headscale

volumes:
  caddy_data:
  caddy_config:
```

### 5. System starten
```bash
sudo docker-compose up -d

# Checken, ob alles läuft (Keine FTL/FATAL Fehler)
sudo docker logs headscale
```

---

## Teil 3: Administration & Geräteregistrierung

### 1. Benutzer verwalten (Auf der VM)
```bash
# Benutzer erstellen
sudo docker exec -it headscale headscale users create privat

# Geräte auflisten
sudo docker exec -it headscale headscale nodes list
```

### 2. Gerät per Express-Verfahren (Pre-Auth-Key) hinzufügen
```bash
# 1. Auf der VM einen Schlüssel generieren (24h gültig):
sudo docker exec -it headscale headscale preauthkeys create --user privat --expiration 24h

# 2. Auf dem Linux-Endgerät ausführen (tritt sofort automatisch bei):
sudo tailscale up --login-server=https://netz.wralto.org --auth-key=mkey:IHR_SCHLÜSSEL --reset
```

### 3. Manuelle Methode (Falls ohne Key gearbeitet wird)
* Auf dem Endgerät: `sudo tailscale up --login-server=https://netz.wralto.org --reset`
* URL im Browser öffnen, den angezeigten Befehl (`headscale auth register...`) kopieren.
* Auf der VM mit vorangestelltem Docker-Befehl ausführen (User `privat` anhängen):
  ```bash
  sudo docker exec -it headscale headscale auth register --auth-id hskey-authreq-xxx --user privat
  ```

---

## Teil 4: Wartungsbefehle
* **Container stoppen:** `sudo docker-compose down`
* **Änderungen anwenden:** `sudo docker-compose down && sudo docker-compose up -d`
* **Backup:** Den Ordner `~/headscale/data` (enthält DB und Schlüssel) sichern.