🦉 Crumbforest Native Deployment

Docker-freie Installation für Linux Server mit fester IP-Adresse.

🌱 Neu hier? Lies zuerst FIRST_STEPS_FOR_GARDENERS.md, bevor du Code änderst.

📦 Inhalt

Dieses Verzeichnis enthält alle Dateien für die native Installation von Crumbforest auf einem Linux-Server ohne Docker.

Verzeichnisstruktur

native_crumbcore_v1/
├── DEPLOYMENT_GUIDE.md              # 📖 Komplette Installations-Anleitung
├── README.md                        # 📄 Diese Datei  
├── env.production.template          # 🔧 Environment Template
├── native-install.sh                # 🚀 Installations-Script
├── native-update.sh                 # 🔄 Update-Script
├── native-backup.sh                 # 💾 Backup-Script
├── systemd/
│   ├── crumbforest.service          # systemd Service (FastAPI)
│   └── crumbforest-indexing.service # systemd Service (Document Indexing)
├── nginx/
│   ├── crumbforest.nginx.conf       # NGINX Server Block
│   └── crumbforest-locations.conf   # NGINX Location Blocks
└── scripts/
    └── init_database.sql            # MariaDB Initialisierung

🎯 Quick Start

Voraussetzungen

✅ Debian 6.1+ Linux Server
✅ Python 3.11+
✅ MariaDB/MySQL
✅ NGINX
✅ Qdrant (localhost:6333)
✅ Root/sudo Zugriff

Installation in 5 Schritten

  1. Repository auf Server clonen:
    bash cd /tmp git clone https://github.com/YOUR_USER/crumbcrm_crumbcore_v1.git crumbforest_deploy

  2. Datenbank einrichten:
    bash mysql -u root -p < scripts/init_database.sql

  3. Installation ausführen:
    bash sudo ./native-install.sh

  4. API Keys konfigurieren:
    bash sudo nano /opt/crumbforest/.env # Trage OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY ein

  5. Services starten:
    bash sudo systemctl start crumbforest-indexing sudo systemctl start crumbforest sudo systemctl reload nginx

Fertig! 🎉

App erreichbar unter: https://crumbforest.<YOUR_IP>.sslip.io

📚 Dokumentation

Siehe DEPLOYMENT_GUIDE.md für:
- Detaillierte Installations-Schritte
- Konfiguration & Sicherheit
- Troubleshooting
- Backup & Wiederherstellung
- Performance Tuning
- Monitoring

🔧 Verfügbare Scripts

Installation

sudo ./native-install.sh

Erstellt komplette Installation unter /opt/crumbforest mit:
- System-User crumbforest
- Python venv mit allen Dependencies
- systemd Services
- NGINX Konfiguration
- Automatisch generierte Secrets

Updates

sudo ./native-update.sh

Aktualisiert Code und Dependencies:
- Stoppt Service
- Erstellt automatisches Backup
- Aktualisiert Code
- Startet Service neu
- Führt Health Check durch

Backup

sudo ./native-backup.sh

Erstellt vollständiges Backup:
- Application Code
- MariaDB Datenbank
- Qdrant Vector DB
- .env Konfiguration
- Logs (7 Tage)

Gespeichert in: /var/backups/crumbforest/

🌐 Server-Konfiguration

Server IP: <YOUR_IP>
Domain: crumbforest.<YOUR_IP>.sslip.io
Installation: /opt/crumbforest
Logs: /var/log/crumbforest + journalctl -u crumbforest

Ports

Service Port Beschreibung
FastAPI 8000 Nur localhost (NGINX Proxy)
NGINX 80, 443 Public HTTP/HTTPS
MariaDB 3306 Nur localhost
Qdrant 6333 Nur localhost

🔐 Sicherheit

  • ✅ Service läuft als dedizierter User crumbforest (nicht root)
  • ✅ .env Datei mit chmod 600 geschützt
  • ✅ NGINX als Reverse Proxy (FastAPI nicht direkt erreichbar)
  • ✅ systemd Security Hardening (NoNewPrivileges, PrivateTmp)
  • ✅ Secrets werden automatisch generiert

Wichtig: Nach Installation unbedingt Standard-Passwörter ändern!

🧪 Verifikation

# Service Status
sudo systemctl status crumbforest

# Logs (Live)
sudo journalctl -u crumbforest -f

# Health Check
curl http://localhost:8000/health

# NGINX Test
curl -I https://crumbforest.194-164-194-191.sslip.io/

⚡ Unterschiede zu Docker

Aspekt Docker Native
Services Container-basiert systemd Services
Netzwerk Docker Network localhost/IP
Datei-System Volumes Direkte Pfade
Updates Image Rebuild rsync + Script
Logs docker logs journalctl
Auto-Start Docker Daemon systemd enable
Isolation Container User Permissions

Environment Variables

Docker:

DATABASE_URL=mysql+pymysql://user:pass@db:3306/dbname
QDRANT_URL=http://qdrant:6333

Native:

DATABASE_URL=mysql+pymysql://user:pass@localhost:3306/dbname
QDRANT_URL=http://localhost:6333

📞 Support & Troubleshooting

Siehe DEPLOYMENT_GUIDE.md Abschnitt "Troubleshooting" für:
- Service startet nicht
- NGINX Fehler
- Qdrant Verbindung
- Database Connection Failed
- Permission Probleme

Logs prüfen:

sudo journalctl -u crumbforest -n 100
tail -f /var/log/nginx/crumbforest.error.log

🎯 Produktions-Checkliste

  • [ ] Datenbank eingerichtet
  • [ ] API Keys konfiguriert
  • [ ] Services starten automatisch
  • [ ] NGINX läuft und proxied korrekt
  • [ ] Health Check erfolgreich
  • [ ] Standard-Passwörter geändert
  • [ ] Firewall konfiguriert (ufw/iptables)
  • [ ] Automatische Backups eingerichtet (Cron)
  • [ ] SSL/HTTPS aktiviert (optional)
  • [ ] Monitoring eingerichtet (optional)

💚 Entwickelt von

Krümel im Keks - Crumbforest Team
Wuuuuhuuu! 🦉