Faktenkompass/README.md

Faktenkompass – Wissensdatenbank für überprüfbare Behauptungen

Eine Django-Webplattform zum schnellen Nachschlagen von Fakten, Quellen und Gegenargumenten 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 Gegenargumenten.

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

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-...

Optional in faktenkompass/settings.py für HTTPS hinter Nginx ergänzen:

SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
CSRF_TRUSTED_ORIGINS = ['https://faktenkompass.example.com']

SECRET_KEY, DEBUG und ALLOWED_HOSTS sollten in der Produktion aus Umgebungsvariablen gelesen werden.

2. Deployment vorbereiten

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

python manage.py migrate
python manage.py collectstatic --noinput
python manage.py createsuperuser   # falls noch nicht vorhanden

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, CounterArgument, 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), Evidenzlevel, Quellen, Gegenargumente, 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, Gegenargumente 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 Gegenargumente 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.