michaelschiemer/deployment/docs/guides/server-rebuild-plan.md

Server-Neuaufbau Plan - Debian 13 (Trixie)

Übersicht

Dieser Plan beschreibt den kompletten Neuaufbau des Production-Servers mit Debian 13 (Trixie) LTS, inklusive aller Infrastructure-Stacks.

Architektur-Entscheidungen

Betriebssystem

• Debian 13 (Trixie) LTS
• UEFI-Version (empfohlen für moderne Server-Hardware)
• Minimale Installation (ohne Desktop)
• SSH-Zugriff konfiguriert
• Firewall (nftables/ufw)

UEFI vs. BIOS

• UEFI empfohlen: Moderner Standard, GPT-Partitionierung, Secure Boot (optional), schnellerer Boot
• BIOS nur wenn: Hardware unterstützt kein UEFI oder Legacy-Systeme vorhanden

Setup-Strategie

• Ansible-basiert: Alle Schritte automatisierbar
• Schrittweise: Basis-Setup → Docker → Infrastructure
• Verifikation: Jeder Schritt wird geprüft

Implementierungs-Phasen

Phase 1: Server-Initialisierung (Netcup Control Panel)

1.1 Server zurücksetzen

Schritte:

1. Netcup Control Panel öffnen
2. Server zurücksetzen/neu installieren
3. Debian 13 (Trixie) auswählen
4. UEFI-Version wählen (empfohlen)
5. Root-Passwort notieren (sicher speichern!)
6. SSH-Key-Option prüfen (falls verfügbar)

Wichtig:

• Alle Daten werden gelöscht - vorher Backups erstellen!
• Neue Server-IP notieren (falls sich ändert)
• DNS-Records müssen ggf. aktualisiert werden

1.2 Initialer SSH-Zugriff

Option A: Mit vorkonfiguriertem deploy-User (empfohlen)

Wenn du beim Server-Setup im Netcup Control Panel:

• Benutzer deploy erstellt hast
• SSH-Key (production.pub) hinzugefügt hast

Dann kannst du direkt verbinden:

# Mit deploy-User verbinden (SSH-Key wird automatisch verwendet)
ssh deploy@<server-ip>
# Oder mit SSH-Config:
ssh production

Option B: Mit Root-Zugriff (falls kein deploy-User erstellt wurde)

# Mit Root-Zugriff verbinden
ssh root@<server-ip>
# Passwort: <root-password-vom-netcup-panel>

# System aktualisieren
apt update && apt upgrade -y

# Basis-Pakete installieren
apt install -y curl wget git vim sudo

Verifikation:

• SSH-Verbindung funktioniert
• System ist aktuell
• Basis-Tools verfügbar

Phase 2: Basis-Setup (Ansible)

2.1 Deploy-User erstellen

Option A: Vorkonfiguriert (empfohlen, wenn beim Server-Setup erstellt)

Wenn du beim Server-Setup im Netcup Control Panel:

• Benutzer deploy erstellt hast
• SSH-Key (production.pub) hinzugefügt hast

Dann kannst du Phase 2.1 überspringen und direkt zu Phase 2.2 gehen!

Verifikation:

# Auf Control-Node
ssh production 'whoami'
# Sollte ausgeben: deploy

Option B: Manuell erstellen (falls nicht beim Setup erstellt)

Manuell (auf Server):

# User anlegen
adduser deploy
usermod -aG sudo deploy

# SSH-Verzeichnis erstellen
mkdir -p /home/deploy/.ssh
chmod 700 /home/deploy/.ssh

SSH-Key hinzufügen (von Control-Node):

# Auf Control-Node
ssh-copy-id -i ~/.ssh/production.pub deploy@<server-ip>

# Oder manuell:
cat ~/.ssh/production.pub | ssh deploy@<server-ip> "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys && chmod 700 ~/.ssh"

SSH-Config auf Control-Node anpassen:

# ~/.ssh/config
Host production
    HostName <server-ip>
    User deploy
    IdentityFile ~/.ssh/production
    ServerAliveInterval 60
    ServerAliveCountMax 3

2.2 Initial Server Setup (Ansible Playbook)

Auf Control-Node:

Mit vorkonfiguriertem deploy-User (empfohlen):

cd deployment/ansible

# Initiales Server-Setup ausführen
# Keine zusätzlichen Parameter nötig - deploy-User und SSH-Key sind bereits konfiguriert
ansible-playbook -i inventory/production.yml \
  playbooks/initial-server-setup.yml

Mit root-User (falls deploy-User nicht erstellt wurde):

cd deployment/ansible

# Initiales Server-Setup ausführen
ansible-playbook -i inventory/production.yml \
  playbooks/initial-server-setup.yml \
  --ask-pass \
  -e "ansible_user=root"

Was das Playbook macht:

• System-Updates (apt update/upgrade)
• Basis-Pakete installieren (curl, wget, git, vim, sudo, ufw, fail2ban)
• Deploy-User konfigurieren (falls nicht vorhanden)
• SSH-Konfiguration (optional: key-only auth)
• Firewall-Setup (optional, standardmäßig deaktiviert)
• Fail2ban konfigurieren

Verifikation:

# Auf Server
whoami  # Sollte ausgeben: deploy
sudo -v  # Sudo-Rechte testen

2.3 Firewall konfigurieren

Option 1: ufw (einfacher)

# Auf Server
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow 51820/udp # WireGuard
sudo ufw enable
sudo ufw status

Option 2: nftables (erweitert)

• Wird später über WireGuard-Playbook konfiguriert
• Admin-Ports nur über VPN

2.3 System-Härtung

SSH-Key-only Authentication:

# Auf Server
sudo nano /etc/ssh/sshd_config

# Ändern:
PasswordAuthentication no
PubkeyAuthentication yes

# Neu starten
sudo systemctl restart sshd

Unattended-Upgrades (via Ansible):

• Wird automatisch über system-Role konfiguriert

Optional: Fail2ban

sudo apt install fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Phase 3: Docker-Installation

3.1 Docker-Repository anpassen

Aktuell: install-docker.yml nutzt Ubuntu-Repository (funktioniert auf Debian)

Optional: Debian-spezifisches Repository nutzen (siehe install-docker.yml)

3.2 Docker installieren (via Ansible)

# Auf Control-Node
cd ~/dev/michaelschiemer/deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/install-docker.yml

Verifikation:

# Auf Server
docker --version
docker compose version
docker run hello-world

Phase 4: Ansible-Setup

4.1 Ansible auf Control-Node

Installation (falls nicht vorhanden):

# Debian/Ubuntu
sudo apt install ansible

# Oder via pip
pip install ansible

Inventory prüfen:

# deployment/ansible/inventory/production.yml
# Server-IP und SSH-Config aktualisieren

SSH-Key-Test:

ansible production -m ping
# Sollte ausgeben: pong

4.2 Ansible-Playbooks anpassen

Geänderte Dateien:

• install-docker.yml: Debian-Repository prüfen/anpassen (optional)
• setup-infrastructure.yml: Verifizieren
• Vault-Secrets prüfen

Phase 5: Infrastructure-Deployment

5.1 Docker installieren (via Ansible)

cd ~/dev/michaelschiemer/deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/install-docker.yml

5.2 Komplettes Infrastructure-Setup

ansible-playbook -i inventory/production.yml \
  playbooks/setup-infrastructure.yml \
  --ask-vault-pass

Deployed Stacks:

• Traefik (Reverse Proxy & SSL)
• PostgreSQL-Production (Database)
• Redis (Cache & Session)
• Docker Registry (Private Registry)
• MinIO (Object Storage)
• Gitea (Git Server)
• Monitoring (Portainer, Grafana, Prometheus)
• Production Application Stack

Erwartete Dauer: 10-20 Minuten

5.3 Staging-Setup (optional, nach Production)

ansible-playbook -i inventory/production.yml \
  playbooks/setup-staging.yml \
  --ask-vault-pass

Phase 6: Verifikation

6.1 Services prüfen

Auf Server:

# Alle Container laufen
docker ps

# Networks vorhanden
docker network ls

# Health-Checks
curl https://michaelschiemer.de/health
curl https://git.michaelschiemer.de

6.2 Ansible-Verifikation

# Auf Control-Node
ansible-playbook -i inventory/production.yml \
  playbooks/verify-production.yml

ansible-playbook -i inventory/production.yml \
  playbooks/verify-staging.yml

Checkliste

Vorbereitung

• Netcup Control Panel Zugriff
• Neuer SSH-Key generiert
• Ansible auf Control-Node installiert
• Vault-Secrets vorbereitet
• DNS-Zugriff (für Domain-Updates)
• Backups erstellt (falls vorhanden)

Phase 1: Server-Initialisierung

• Server zurückgesetzt
• Debian 13 (Trixie) installiert
• UEFI-Version gewählt
• Root-Passwort notiert
• Initialer SSH-Zugriff funktioniert
• System aktualisiert

Phase 2: Basis-Setup

• Deploy-User erstellt
• SSH-Key hinzugefügt
• SSH-Config angepasst
• Firewall konfiguriert
• System gehärtet

Phase 3: Docker-Installation

• Docker installiert
• Docker Compose installiert
• Deploy-User in docker-Gruppe
• Docker-Test erfolgreich

Phase 4: Ansible-Setup

• Ansible installiert
• Inventory aktualisiert
• SSH-Key-Test erfolgreich
• Playbooks geprüft

Phase 5: Infrastructure-Deployment

• Docker installiert (via Ansible)
• Infrastructure-Setup erfolgreich
• Alle Stacks deployed
• Staging-Setup (optional)

Phase 6: Verifikation

• Services laufen
• Networks vorhanden
• Health-Checks erfolgreich
• Ansible-Verifikation erfolgreich

Wichtige Hinweise

1. SSH-Key-Sicherheit: Neuen SSH-Key generieren und sicher speichern
2. Vault-Secrets: Alle Secrets in Ansible Vault verschlüsselt
3. Backup-Strategie: Vor Neuaufbau alle Daten sichern (falls vorhanden)
4. DNS-Konfiguration: Domains müssen auf neue Server-IP zeigen
5. Rollback-Plan: Alte Server-Konfiguration dokumentieren

Troubleshooting

SSH-Verbindung fehlgeschlagen

• Firewall-Regeln prüfen
• SSH-Key-Berechtigungen prüfen (600)
• SSH-Config prüfen

Docker-Installation fehlgeschlagen

• Repository-URL prüfen
• GPG-Key prüfen
• Netzwerk-Verbindung prüfen

Ansible-Playbook fehlgeschlagen

• Inventory-Datei prüfen
• SSH-Zugriff testen: ansible production -m ping
• Vault-Passwort prüfen

Infrastructure-Deployment fehlgeschlagen

• Docker läuft?
• Networks vorhanden?
• Secrets korrekt?
• Logs prüfen: docker logs <container>

Nächste Schritte nach Neuaufbau

1. Monitoring einrichten
2. Backup-Strategie verifizieren
3. Staging-Environment testen
4. CI/CD-Pipeline testen
5. Dokumentation aktualisieren

Referenzen

• deployment/docs/guides/ssh-access.md - SSH-Zugriff Dokumentation
• deployment/ansible/playbooks/initial-server-setup.yml - Basis-Setup Playbook
• deployment/ansible/playbooks/install-docker.yml - Docker-Installation
• deployment/ansible/playbooks/setup-infrastructure.yml - Infrastructure-Setup