🌳 Crumbforest Deployment

Saubere HTTPS Subdomain-Architektur für Crumbforest
Von Krümeln für Krümel - Schritt für Schritt erklärt!

🎯 Was macht dieses Repo?

Dieses Repo hilft dir, deine Crumbforest-Installation sicher und sauber aufzusetzen:

• ✅ HTTPS-only - Keine unsicheren HTTP-Verbindungen mehr
• ✅ Subdomain-Struktur - Jeder Service hat seine eigene Domain
• ✅ Authentication - Alle sensiblen Bereiche sind geschützt
• ✅ Automatische Installation - Script macht die Arbeit für dich
• ✅ Umfassende Tests - Prüfe ob alles funktioniert

🌟 Für wen ist das?

Du bist hier richtig, wenn du:
- 🌱 Neu in Linux/Nginx bist
- 🔧 Crumbforest sicher betreiben willst
- 📚 Lernen möchtest wie Web-Server funktionieren
- 🛡️ Kinder-Daten schützen willst

Keine Sorge: Wir erklären jeden Schritt! 💚

📋 Was du brauchst

✅ Checkliste

• [ ] Einen Linux Server (Ubuntu 20.04+ empfohlen)
• [ ] Root-Zugriff (oder sudo)
• [ ] Einen Domainnamen oder sslip.io (kostenlos!)
• [ ] 30 Minuten Zeit für die Installation
• [ ] Eine Tasse Tee ☕

💻 Dein Server sollte haben:

• Nginx installiert (nginx -v)
• Certbot für SSL (certbot --version)
• SSH-Zugang (ssh root@DEINE-IP)
• Ports offen: 80 (HTTP) und 443 (HTTPS)

Nicht sicher? Siehe Server-Vorbereitung

🚀 Schnellstart (für Erfahrene)

# 1. Repo klonen
git clone https://github.com/DEIN-USER/crumbforest-deployment.git
cd crumbforest-deployment

# 2. Auf Server kopieren
scp -r * root@DEINE-IP:/root/crumbforest-deployment/

# 3. Deployment
ssh root@DEINE-IP
cd /root/crumbforest-deployment
chmod +x scripts/setup_subdomains.sh
./scripts/setup_subdomains.sh

# 4. Testen
chmod +x scripts/run_all_tests.sh
./scripts/run_all_tests.sh

📖 Schritt-für-Schritt für Einsteiger

Neu in Linux? Kein Problem! Folge dieser Anleitung:

Schritt 1: Verstehen was passiert

👉 Was wird gemacht? - Lies das zuerst!

Schritt 2: Server vorbereiten

👉 Server-Vorbereitung - Installiere benötigte Programme

Schritt 3: Auth einrichten

👉 Authentication Setup - Erstelle Passwörter

Schritt 4: Deployment

👉 Installation - Folge der Anleitung!

Schritt 5: Testen

👉 Tests durchführen - Prüfe ob alles läuft

Schritt 6: Im Alltag

👉 Daily Operations - Tägliche Aufgaben

🗂️ Repository-Struktur

crumbforest-deployment/
├── 📄 README.md                    ← Du bist hier!
├── 📄 LICENSE
├── 📄 .gitignore
│
├── 📁 docs/                        ← Alle Dokumentationen
│   ├── ARCHITECTURE.md             → Was wird gemacht?
│   ├── PREREQUISITES.md            → Server vorbereiten
│   ├── INSTALLATION.md             → Schritt-für-Schritt
│   ├── AUTH_SETUP.md               → Passwörter einrichten
│   ├── TESTING.md                  → Tests durchführen
│   ├── TROUBLESHOOTING.md          → Häufige Probleme lösen
│   ├── QUICK_REFERENCE.md          → Tägliche Befehle
│   ├── SECURITY_CHECKLIST.md       → Security-Checks
│   ├── GLOSSARY.md                 → Begriffe erklärt
│   └── FAQ.md                      → Häufige Fragen
│
├── 📁 configs/                     ← Nginx Konfigurationen
│   ├── 00_catch_all.conf           → HTTP→HTTPS Redirect
│   ├── crumbforest.conf            → 🌳 Crumbforest App
│   ├── ttyd.conf                   → 💻 Terminal
│   ├── gitea.conf                  → 📦 Gitea
│   ├── qdrant.conf                 → 🔍 Qdrant
│   └── main_redirect.conf          → Hauptdomain redirect
│
├── 📁 scripts/                     ← Automatisierungs-Scripts
│   ├── setup_subdomains.sh         → Haupt-Deployment-Script
│   ├── run_all_tests.sh            → Test-Suite
│   ├── create_backup.sh            → Manuelles Backup
│   └── rollback.sh                 → Zurück zur alten Config
│
└── 📁 examples/                    ← Beispiele
    ├── .htpasswd.example           → Beispiel Auth-Datei
    ├── test_output.txt             → Wie Tests aussehen sollen
    └── curl_examples.sh            → Test-Commands

⚡ Was passiert beim Deployment?

Vorher (Chaos):

❌ Services mehrfach konfiguriert
❌ HTTP noch offen (unsicher!)
❌ Keine Authentifizierung
❌ Unübersichtliche Config

Nachher (Sauber):

✅ Jeder Service eine Subdomain
✅ HTTPS-only (alles verschlüsselt)
✅ Auth auf allen Services
✅ Klare Struktur

Deine neuen URLs:

🌳 Crumbforest:  https://crumbforest.194-164-194-191.sslip.io
💻 Terminal:     https://ttyd.194-164-194-191.sslip.io
📦 Gitea:        https://git.194-164-194-191.sslip.io
🔍 Qdrant:       https://qdrant.194-164-194-191.sslip.io

🛡️ Sicherheit

Was wird geschützt?

Wichtig: Ohne Passwort → Kein Zugriff! 🔒

Security-Features:

• ✅ HTTPS-Verschlüsselung (TLS 1.2/1.3)
• ✅ Automatische HTTP→HTTPS Umleitung
• ✅ HSTS (Browser merken sich HTTPS)
• ✅ Basic Authentication überall
• ✅ Token-Auth für APIs
• ✅ Separate Auth-Files für flexible Verwaltung

#ckl - Wächter aktiv auf allen Vektoren! 🛡️

🚨 Häufige Stolpersteine (und wie du sie vermeidest!)

1. "Permission denied" beim Kopieren

Problem: Du hast keine Rechte auf dem Server
Lösung: Nutze sudo oder logge dich als root ein

# Statt:
scp file.conf user@server:/etc/nginx/

# Mache:
scp file.conf root@server:/root/

2. "nginx -t" zeigt Fehler

Problem: Syntax-Fehler in Config oder Datei fehlt
Lösung: Prüfe die Fehlermeldung genau!

nginx -t
# Lies die Fehlermeldung und prüfe:
# - Ist die Datei am richtigen Ort?
# - Fehlt ein Semikolon (;)?
# - Existiert die .htpasswd Datei?

3. "Connection refused" beim curl

Problem: Backend-Service läuft nicht
Lösung: Starte den Service

# Prüfe Status
systemctl status crumbforest  # oder dein Service-Name

# Starte falls nötig
systemctl start crumbforest

4. "Certificate not found"

Problem: SSL-Zertifikat fehlt
Lösung: Erstelle es mit Certbot

certbot certonly --nginx -d deine-domain.sslip.io

5. Passwort falsch eingegeben

Problem: .htpasswd Datei wurde nicht korrekt erstellt
Lösung: Erstelle neu

# Lösche alte Datei
rm /etc/nginx/.htpasswd

# Erstelle neu (mit -c für "create")
htpasswd -c /etc/nginx/.htpasswd username

Mehr Hilfe? Siehe Troubleshooting

🧪 Testen ob alles funktioniert

Nach dem Deployment solltest du testen:

# 1. Automatische Tests
./scripts/run_all_tests.sh

# 2. Manuell eine URL testen
curl -I https://crumbforest.194-164-194-191.sslip.io/
# Sollte zeigen: 401 Unauthorized (Auth ist aktiv!)

# 3. Mit Passwort testen
curl -I -u username:password https://crumbforest.194-164-194-191.sslip.io/
# Sollte zeigen: 200 OK

Alle Tests grün? 🎉 Glückwunsch, du bist fertig!

📚 Dokumentation

Wir haben ausführliche Docs für jeden Schritt:

🤝 Mitmachen

Du hast Verbesserungen? Pull Requests willkommen! 💚

1. Fork das Repo
2. Erstelle einen Branch (git checkout -b feature/verbesserung)
3. Committe deine Änderungen (git commit -am 'Beschreibung')
4. Push zum Branch (git push origin feature/verbesserung)
5. Erstelle einen Pull Request

Fragen? Öffne ein Issue!

📜 Lizenz

MIT License - siehe LICENSE

Das bedeutet: Du darfst das Repo frei nutzen, ändern und teilen! 🎉

🙏 Credits

Entwickelt für die Crumbforest Community
Mit 💚 von Krümeln für Krümel

Besonderer Dank an:
- Alle Tester und Feedback-Geber
- Die Open-Source Community
- Nginx, Certbot, und alle genutzten Tools

📞 Support

Brauchst du Hilfe?

1. Schau in die FAQ - Vielleicht ist deine Frage schon beantwortet
2. Prüfe Troubleshooting - Häufige Probleme & Lösungen
3. Öffne ein Issue - Wir helfen gerne!

Hast du einen Bug gefunden?

Bitte öffne ein Issue mit:
- 🐛 Beschreibung des Problems
- 📋 Schritte zum Reproduzieren
- 💻 Deine System-Infos (OS, Nginx-Version)
- 📸 Screenshots (falls relevant)

🎯 Status

• ✅ Production Ready - Kann in Produktion eingesetzt werden
• ✅ Security Hardened - Alle Sicherheits-Best-Practices
• ✅ Tested - Umfassende Test-Suite
• ✅ Documented - Ausführliche Dokumentation

Version: 2.0
Last Updated: 2025-01-14
Status: #ckl 🛡️

🌳 Über Crumbforest

Wo Fragen wachsen. Und jeder Krümel geschützt ist.

Crumbforest ist ein offenes Lern-Ökosystem mit Kindern, Maschinen und Natur.

Mehr Infos: https://crumbforest.194-164-194-191.sslip.io