Homelab Wiki

Writing /data/dokuwiki/data/cache/a/a16e906024bf7152fa4f7bea0878eb69.i failed
Unable to save cache file. Hint: disk full; file permissions; safe_mode setting.
Writing /data/dokuwiki/data/cache/a/a16e906024bf7152fa4f7bea0878eb69.xhtml failed
This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Bootstrap Guide ======

Komplettanleitung zum Aufbau des Automation Stacks von Grund auf.

===== Übersicht =====

<code>
DAY 0 (manuell)          DAY 1 (automatisiert)         DAY 2
─────────────────        ─────────────────────         ──────────
Proxmox                  bootstrap.sh                  Operations
Cloudflare               └─► LXCs erstellen            • Monitoring
vault.yml                └─► Services deployen         • Updates
Inventory wählen         └─► Firewall-Regeln           • Ansible
</code>

===== DAY 0 — Foundation =====

==== Inventory Environment wählen ====

Der Stack unterstützt mehrere Environments über Inventory-Dateien:

  * **Home environment**: ''ansible/inventory.yml'' (default)
    * Netzwerk: 10.100.161.0/24
    * Proxmox node: "pve"
    * Domain: home.miskam.xyz
  * **Hetzner environment**: ''ansible/inventory-hetzner.yml''
    * Netzwerk: 10.10.10.0/24
    * Proxmox node: "hv-test"
    * Domain: test.miskam.xyz

**Eigenes Environment hinzufügen:**

<code bash>
# 1. Inventory kopieren
cp ansible/inventory.yml ansible/inventory-production.yml

# 2. Anpassen
vim ansible/inventory-production.yml
</code>

In der Inventory-Datei definieren:
  * ''network.prefix'': z.B. "10.20.30" → Container bekommen 10.20.30.110-117
  * ''network.gateway'': Gateway des Netzwerks
  * ''domain'': Basis-Domain für Services
  * ''proxmox.hosts'': Proxmox-Host und IP
  * ''automation_stack.hosts'': Container-IDs und Hostnames

Beispiel Hetzner:
<code yaml>
all:
  vars:
    network:
      prefix: "10.10.10"
      gateway: "10.10.10.1"
      nameserver: "10.10.10.1"
    domain: test.miskam.xyz

  children:
    proxmox:
      hosts:
        hv-test:
          ansible_host: 91.107.196.96

    automation_stack:
      hosts:
        traefik:
          ct_id: 110
          ct_hostname: traefik
          # ... weitere Container
</code>

==== Cloudflare ====

**Domain hinzufügen:**
  - Domain → Cloudflare DNS

**API Token erstellen:**
  - My Profile → API Tokens → Create Token
  - Template: "Edit zone DNS"
  - Zone: Deine Domain
  - → Token speichern für vault.yml

**DNS Records:**

^ Type ^ Name ^ Value ^
| A | *.home.miskam.xyz | <WAN-IP> |
| A | *.test.miskam.xyz | <Hetzner-IP> |

==== Proxmox ====

=== lokal (Home) ===

**Installation:**
  * ISO von proxmox.com
  * Storage: local-lvm (LXC root disks)
  * Netzwerk: vmbr0 als VLAN-aware Bridge

**Bridge-Konfiguration** (''/etc/network/interfaces''):
<code>
cat > /etc/network/interfaces <<EOF
auto vmbr0
iface vmbr0 inet manual
    bridge-ports enp1s0
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes
EOF
ifreload -a
</code>

=== Hetzner VPS ===

**NAT-Setup für private Netzwerk:**

<code>
cat > /etc/network/interfaces <<EOF
auto lo
iface lo inet loopback

auto eno1
iface eno1 inet static
        address  91.107.196.96/24
        gateway  91.107.196.1

auto vmbr0
iface vmbr0 inet static
        address  10.10.10.1/24
        bridge-ports none
        bridge-stp off
        bridge-fd 0

        post-up   echo 1 > /proc/sys/net/ipv4/ip_forward
        post-up   iptables -t nat -A POSTROUTING -s '10.10.10.0/24' -o eno1 -j MASQUERADE
        post-down iptables -t nat -D POSTROUTING -s '10.10.10.0/24' -o eno1 -j MASQUERADE
EOF
ifreload -a
</code>

**Port-Forwarding** (Ports 80/443 → Traefik):

Nach Bootstrap einmalig ausführen:
<code bash>
cd ansible
ansible-playbook configure-nat.yml --vault-password-file ../.vault_pass
</code>

**API Token erstellen:**
  * Datacenter → Permissions → API Tokens
  * User: root@pam
  * Token ID: ansible
  * **Privilege Separation: aus** (wichtig!)
  * → Token speichern für vault.yml

==== vault.yml vorbereiten ====

<code bash>
# 1. Vault-Passwort erstellen
echo 'dein-sicheres-passwort' > .vault_pass
chmod 600 .vault_pass

# 2. Vault generieren (mit Platzhaltern)
./bootstrap.sh --generate-vault

# 3. Anpassen
vim vault.yml
</code>

**Pflichtfelder:**
  * ''cloudflare_email'': Cloudflare Account Email
  * ''cloudflare_api_token'': API Token von Cloudflare
  * ''proxmox_api_token_secret'': Token-Secret von Proxmox
  * ''proxmox_node'': Node-Name ("pve" oder "hv-test")
  * ''domain'': Muss mit Inventory übereinstimmen

**Optional (werden auto-generiert):**
  * Alle Passwörter und Encryption Keys
  * ''proxmox_storage'': Default "local-lvm"

<code bash>
# 4. Verschlüsseln
./bootstrap.sh --encrypt
</code>

===== DAY 1 — Bootstrap =====

==== Bootstrap starten ====

**Home environment (default):**
<code bash>
./bootstrap.sh
</code>

**Hetzner environment:**
<code bash>
INVENTORY_FILE=ansible/inventory-hetzner.yml ./bootstrap.sh
</code>

**Eigenes environment:**
<code bash>
INVENTORY_FILE=ansible/inventory-production.yml ./bootstrap.sh
</code>

==== Ablauf (automatisch) ====

<code>
bootstrap.sh
    │
    ├─► 1. Validierung
    │       ├── Cloudflare API
    │       ├── SSH Keys
    │       └── vault.yml
    │
    ├─► 2. LXC Container (via Proxmox API)
    │       ├── Traefik (110)
    │       ├── PostgreSQL (111)
    │       ├── n8n (112)
    │       ├── Vaultwarden (113)
    │       ├── DokuWiki (114)
    │       ├── Uptime Kuma (115)
    │       ├── Monitoring (116)
    │       └── Forgejo (117)
    │
    ├─► 3. SSH Key Injection
    │       └── Alle Container SSH-fähig
    │
    ├─► 4. Base Packages
    │       └── curl, git, ufw, etc.
    │
    ├─► 5. Service Deployment
    │       ├── Traefik (Reverse Proxy + SSL)
    │       ├── PostgreSQL (Shared DB)
    │       ├── n8n (Workflow Automation)
    │       ├── Vaultwarden (Password Manager)
    │       ├── DokuWiki (Wiki)
    │       ├── Uptime Kuma (Monitoring)
    │       ├── Prometheus + Grafana (Metrics)
    │       └── Forgejo (Git Server)
    │
    └─► 6. Firewall-Regeln
            └── Automatisch pro Service
</code>

**Dauer:** 15-20 Minuten (abhängig von Netzwerk-Geschwindigkeit)

==== Container-Übersicht ====

^ CT ^ Name ^ IP (Suffix) ^ RAM ^ Disk ^ Ports ^
| 110 | traefik | .110 | 512M | 2G | 80,443,2222,8080 |
| 111 | postgres | .111 | 1G | 8G | 5432 |
| 112 | n8n | .112 | 1G | 4G | 5678 |
| 113 | vaultwarden | .113 | 512M | 2G | 8080 |
| 114 | dokuwiki | .114 | 512M | 2G | 80 |
| 115 | uptime-kuma | .115 | 512M | 2G | 3001 |
| 116 | monitoring | .116 | 1G | 4G | 9090,3000 |
| 117 | forgejo | .117 | 512M | 4G | 3000 |

IP-Suffix wird an ''network.prefix'' aus Inventory angehängt.
Beispiel: Home = 10.100.161.110, Hetzner = 10.10.10.110

==== Firewall-Regeln (automatisch) ====

Jeder Service konfiguriert seine eigenen Firewall-Regeln:

  * **PostgreSQL (111)**: Erlaubt 5432 von n8n, vaultwarden, forgejo
  * **n8n (112)**: Erlaubt 5678 von traefik
  * **Vaultwarden (113)**: Erlaubt 8080 von traefik
  * **DokuWiki (114)**: Erlaubt 80 von traefik
  * **Uptime Kuma (115)**: Erlaubt 3001 von traefik
  * **Monitoring (116)**: Erlaubt 3000+9090 von traefik
  * **Forgejo (117)**: Erlaubt 3000 von traefik
  * **Alle Container**: node_exporter (9100) von monitoring

Regeln werden automatisch beim Service-Deployment angewendet.

===== DAY 2 — Operations =====

==== Service-URLs ====

^ Service ^ URL ^
| n8n | https://n8n.domain |
| Vaultwarden | https://vault.domain |
| DokuWiki | https://wiki.domain |
| Uptime Kuma | https://status.domain |
| Grafana | https://monitoring.domain |
| Forgejo | https://git.domain |
| Traefik Dashboard | https://traefik.domain |

==== Ansible Operations ====

**Alle Services neu deployen:**
<code bash>
cd ansible
ansible-playbook site.yml --vault-password-file ../.vault_pass

# Hetzner:
ansible-playbook -i inventory-hetzner.yml site.yml --vault-password-file ../.vault_pass
</code>

**Einzelner Service:**
<code bash>
ansible-playbook site.yml --limit n8n --vault-password-file ../.vault_pass
</code>

**Vault editieren:**
<code bash>
ansible-vault edit ../vault.yml --vault-password-file ../.vault_pass
</code>

**Connectivity testen:**
<code bash>
ansible automation_stack -m ping --vault-password-file ../.vault_pass

# Hetzner:
ansible -i inventory-hetzner.yml automation_stack -m ping --vault-password-file ../.vault_pass
</code>

===== Besonderheiten =====

==== Traefik Rate Limiting ====

  * **n8n**: Kein Rate Limiting (80+ Assets beim ersten Laden)
  * **Andere Services**: 100 req/s, burst 100 (global)
  * **Auth Services**: 5 req/s, burst 10 (vaultwarden, grafana, forgejo)

==== Traefik SSH Port ====

Traefik verwendet Port 2222 für SSH, weil Port 22 an Forgejo weitergeleitet wird (Git SSH).

==== Container Teardown ====

Zum vollständigen Entfernen aller Container:
<code bash>
# Mit Bestätigung
./teardown.sh --confirm

# Oder direkt via Ansible
cd ansible
ansible-playbook teardown.yml --vault-password-file ../.vault_pass
</code>

----

//Erstellt: 2026-02-07 | Aktualisiert: 2026-02-10//