🌲 Crumbforest Crew Chat — Fresh Host Deployment

Diese Anleitung beschreibt Schritt für Schritt, wie man den Crumbforest Crew Chat (CrumbIRC) auf einem komplett frischen Ubuntu/Debian-Server installiert. Das System nutzt Nginx, PostgreSQL mit pgvector und einen lokalen Ollama-Dienst.

1. System aktualisieren & Pakete installieren

sudo apt update && sudo apt upgrade -y
sudo apt install -y postgresql postgresql-contrib postgresql-server-dev-14 \
                    nginx python3-venv python3-pip git curl make gcc

(Hinweis: Die PostgreSQL-Version kann je nach OS abweichen, z. B. postgresql-server-dev-16 bei Ubuntu 24.04).

2. pgvector installieren

Da der Chat ein RAG-basiertes "Waldgedächtnis" (Vektordatenbank) nutzt, benötigen wir die pgvector Extension:

cd /tmp
git clone --branch v0.6.0 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

3. PostgreSQL vorbereiten

Wir legen den User crumbforest und die Datenbank crumbforest_db an.

sudo -u postgres psql -c "CREATE USER crumbforest WITH PASSWORD 'crumbforest';"
sudo -u postgres psql -c "CREATE DATABASE crumbforest_db OWNER crumbforest;"
sudo -u postgres psql -d crumbforest_db -c "CREATE EXTENSION IF NOT EXISTS vector;"

Optional: Passwort in der App ändern, falls gewünscht.

4. Verzeichnisse & Python Venv anlegen

Die App liegt standardmäßig unter /opt/crumbforest/.

sudo mkdir -p /opt/crumbforest/chat/public
sudo mkdir -p /opt/crumbforest/forest
sudo chown -R $USER:$USER /opt/crumbforest

cd /opt/crumbforest
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install flask flask-cors flask-socketio psycopg2-binary requests fastembed

5. Ollama installieren (Lokale KI)

curl -fsSL https://ollama.com/install.sh | sh
ollama run gemma:2b

6. Systemd Service einrichten

Damit die API (Port 5001) immer im Hintergrund läuft, legen wir einen Systemd-Service an:

sudo nano /etc/systemd/system/forest-api.service

Inhalt:

[Unit]
Description=Crumbforest API (Crew Chat)
After=network.target postgresql.service ollama.service

[Service]
User=root
WorkingDirectory=/opt/crumbforest/forest
Environment="FOREST_DB=crumbforest_db"
Environment="FOREST_USER=crumbforest"
Environment="FOREST_PASS=crumbforest"
Environment="OLLAMA_MODEL=gemma:2b"
ExecStart=/opt/crumbforest/venv/bin/python3 /opt/crumbforest/forest/forest_api.py
Restart=always

[Install]
WantedBy=multi-user.target

Aktivieren:

sudo systemctl daemon-reload
sudo systemctl enable forest-api

7. Applikation ausrollen

Wechsle in das Verzeichnis mit dem deploy_v2.sh Skript und führe es aus.
Das Skript erledigt den Rest: Datenbanktabellen (migrate_chat.sql) werden angelegt, Nginx-Profile kopiert und der Service neu gestartet.

sudo ./deploy_v2.sh

8. Basic Auth (Crew Zugang) anlegen

Der Chat ist über eine .htpasswd Datei geschützt. Die User dort generieren gleichzeitig auch den Chat-Namen ("Nick"), wenn der User den Chat betritt.

sudo htpasswd -cB /etc/nginx/.crumbchat_users DEIN_NICKNAME

Das -c Flag erstellt eine neue Datei (nur beim ersten User benutzen!).
Danach den Nginx noch einmal prüfen und neu laden:

sudo nginx -t && sudo systemctl reload nginx

Fertig! Die Anwendung ist nun unter deiner konfigurierten Domain (bzw. chat.crumbforest.io) erreichbar. 🌲✨