Faktenkompass/README.md

Faktenkompass – Wissensdatenbank für überprüfbare Behauptungen

Eine Django-Webplattform zum schnellen Nachschlagen von Fakten, Quellen und Antworten zu häufigen Aussagen in Diskussionen.

Voraussetzungen

• Python 3.10 oder höher
• pip

Installation

1. Virtuelle Umgebung erstellen

cd /pfad/zu/ArgumentAtlas
python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

Falls python3 -m venv fehlschlägt, nutzen Sie explizit den System-Python:

/usr/bin/python3 -m venv .venv

2. Abhängigkeiten installieren

pip install -r requirements.txt

3. Datenbank migrieren

python manage.py migrate

4. Beispieldaten laden

python manage.py load_sample_data

Dies erstellt 7 Kategorien mit insgesamt 15 Behauptungen, Quellen und möglichen Antworten.

5. Admin-Zugang einrichten

python manage.py createsuperuser

6. Entwicklungsserver starten

python manage.py runserver

Die Anwendung ist unter http://127.0.0.1:8000/ erreichbar.
Das Django-Admin-Interface liegt unter http://127.0.0.1:8000/admin/.

Falls runserver mit einem Python-Pfadfehler abbricht, starten Sie mit:

python manage.py runserver --noreload

PostgreSQL (Produktion)

Setzen Sie folgende Umgebungsvariablen:

export DB_ENGINE=django.db.backends.postgresql
export DB_NAME=faktenkompass
export DB_USER=ihr_benutzer
export DB_PASSWORD=ihr_passwort
export DB_HOST=localhost
export DB_PORT=5432

Installieren Sie zusätzlich psycopg2-binary und führen Sie migrate erneut aus.

Produktion (Daphne + Nginx)

Für den Serverbetrieb wird Daphne als ASGI-Server empfohlen. Nginx dient als Reverse Proxy und liefert statische Dateien sowie Uploads aus.

1. Umgebungsvariablen

Legen Sie z. B. /etc/faktenkompass.env an:

DJANGO_SETTINGS_MODULE=faktenkompass.settings
DJANGO_DEBUG=False
DJANGO_SECRET_KEY=lange-zufaellige-zeichenkette
ALLOWED_HOSTS=faktenkompass.example.com,www.faktenkompass.example.com
CSRF_TRUSTED_ORIGINS=https://faktenkompass.example.com,https://www.faktenkompass.example.com
USE_HTTPS=True

DB_ENGINE=django.db.backends.postgresql
DB_NAME=faktenkompass
DB_USER=faktenkompass
DB_PASSWORD=geheim
DB_HOST=127.0.0.1
DB_PORT=5432

OPENAI_API_KEY=sk-...

CSRF_TRUSTED_ORIGINS muss die exakte URL sein, mit der Sie die Seite aufrufen (Schema + Domain, ohne Pfad). Bei HTTP statt HTTPS z. B. http://192.168.178.10 setzen und USE_HTTPS=False.

USE_HTTPS=True aktiviert Proxy-Header und sichere Cookies hinter Nginx mit HTTPS.

2. Deployment vorbereiten

cd /pfad/zu/ArgumentAtlas
source .venv/bin/activate
pip install -r requirements.txt

set -a && source /etc/faktenkompass.env && set +a
python manage.py migrate
python manage.py collectstatic --noinput
python manage.py createsuperuser   # falls noch nicht vorhanden

Wichtig: collectstatic immer mit denselben Umgebungsvariablen ausführen wie der Daphne-Dienst (DJANGO_DEBUG=False). Sonst fehlen gehashte Dateinamen bzw. staticfiles.json und die Seite antwortet mit 500.

Nach jedem git pull mit geänderten Static-Dateien:

set -a && source /etc/faktenkompass.env && set +a
python manage.py collectstatic --clear --noinput
sudo systemctl restart faktenkompass

Erfolg prüfen: staticfiles/staticfiles.json existiert, CSS heißt z. B. custom.<hash>.css.

Stellen Sie sicher, dass der Prozessnutzer Schreibrechte für media/ und die Datenbank hat.

3. Daphne manuell testen

set -a && source /etc/faktenkompass.env && set +a
daphne -b 127.0.0.1 -p 8001 faktenkompass.asgi:application

Die App lauscht dann nur lokal auf Port 8001 – der öffentliche Zugriff erfolgt über Nginx.

4. systemd-Dienst

Datei /etc/systemd/system/faktenkompass.service:

[Unit]
Description=Faktenkompass (Daphne ASGI)
After=network.target postgresql.service

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/pfad/zu/ArgumentAtlas
EnvironmentFile=/etc/faktenkompass.env
ExecStart=/pfad/zu/ArgumentAtlas/.venv/bin/daphne \
    -b 127.0.0.1 \
    -p 8001 \
    --access-log /var/log/faktenkompass/access.log \
    --proxy-headers \
    faktenkompass.asgi:application
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Log-Verzeichnis anlegen und Dienst aktivieren:

sudo mkdir -p /var/log/faktenkompass
sudo chown www-data:www-data /var/log/faktenkompass
sudo systemctl daemon-reload
sudo systemctl enable --now faktenkompass
sudo systemctl status faktenkompass

--proxy-headers setzt voraus, dass Nginx die Header X-Forwarded-For, X-Forwarded-Proto und Host korrekt weitergibt.

5. Nginx-Konfiguration

Datei /etc/nginx/sites-available/faktenkompass:

upstream faktenkompass {
    server 127.0.0.1:8001;
}

server {
    listen 80;
    server_name faktenkompass.example.com;

    client_max_body_size 25M;

    location /static/ {
        alias /pfad/zu/ArgumentAtlas/staticfiles/;
        expires 30d;
        access_log off;
    }

    location /media/ {
        alias /pfad/zu/ArgumentAtlas/media/;
        expires 7d;
        access_log off;
    }

    location / {
        proxy_pass http://faktenkompass;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }
}

Aktivieren und testen:

sudo ln -s /etc/nginx/sites-available/faktenkompass /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Für HTTPS: Certbot/Let's Encrypt verwenden (certbot --nginx).

6. Updates einspielen

cd /pfad/zu/ArgumentAtlas
source .venv/bin/activate
git pull
pip install -r requirements.txt
python manage.py migrate
python manage.py collectstatic --noinput
sudo systemctl restart faktenkompass

Projektstruktur

ArgumentAtlas/
├── faktenkompass/          # Django-Projektkonfiguration
│   ├── settings.py
│   └── urls.py
├── claims/                 # Haupt-App
│   ├── models.py           # Category, Claim, Source, EvidenceFile, PossibleAnswer, Tag
│   ├── views.py
│   ├── urls.py
│   ├── admin.py
│   └── management/commands/load_sample_data.py
├── templates/              # Django-Templates (Bootstrap 5)
├── static/css/custom.css   # Minimales Custom-Styling
├── requirements.txt
└── manage.py

Funktionen

• Startseite: Kategorien als Karten mit Behauptungsanzahl
• Kategorieseite: Behauptungen filtern und durchsuchen
• Behauptungsdetail: Status, Kurzantwort, Nachweise (Bilder/PDFs), Quellen, mögliche Antworten, Tags
• Globale Suche: Behauptungen über alle Kategorien hinweg
• Admin: Alle Inhalte über Django Admin pflegen
• SEO: Sprechende URLs (/kategorie/klimawandel/, /behauptung/...)

Inhalte verwalten

Melden Sie sich im Django-Admin an, um Kategorien, Behauptungen, Quellen, mögliche Antworten und Schlagwörter anzulegen oder zu bearbeiten. Slugs werden automatisch aus Titeln generiert.

Nachweise hochladen

Bei jeder Behauptung können im Admin unter Nachweise Dateien hochgeladen werden:

• Bilder: JPG, PNG, GIF, WebP, SVG (z. B. Grafiken, Screenshots, Diagramme)
• PDFs: Studien, Berichte, Faktenblätter

Optional: Titel, Bildunterschrift und Reihenfolge. Hochgeladene Dateien erscheinen auf der Behauptungsdetailseite im Abschnitt „Nachweise“.

Dateien werden unter media/evidence/ gespeichert. In der Produktion muss der Webserver Medien-Dateien ausliefern (z. B. über Nginx).

Fakten-Assistent (KI im Admin)

Der Assistent hilft beim Anlegen neuer Behauptungen per ChatGPT. Nichts wird automatisch veröffentlicht – jeder Entwurf muss zuerst geprüft werden.

Einrichtung:

export OPENAI_API_KEY=sk-...
# optional: OPENAI_MODEL=gpt-4o-mini, OPENAI_MODEL_VISION=gpt-4o

Nutzung:

1. Admin öffnen → Fakten-Assistent (Startseite oder unter Fakten-Entwürfe)
2. Artikel-URL, Beschreibung und/oder Bild/PDF eingeben
3. Entwurf generieren – die KI schlägt Kategorie, Behauptung, Quellen und mögliche Antworten vor
4. Entwurf prüfen, bearbeiten, ggf. KI erneut fragen
5. Erst mit Veröffentlichen wird der Eintrag live geschaltet

Sicherheit:

• Nur für eingeloggte Staff-Nutzer
• Artikel-URLs: SSRF-Schutz (keine internen/privaten Adressen)
• API-Schlüssel nur serverseitig (Umgebungsvariable), nie im Frontend
• Hochgeladene Dateien werden erst nach Freigabe als Nachweis verknüpft

Lizenz

Projekt für den internen Gebrauch / Bildungszwecke.