StiftOS FörderPortal

Das StiftOS FörderPortal ist eine selbst gehostete Webanwendung, die Stiftungen, Bürgerstiftungen und NGOs dabei unterstützt, Förderanträge digital zu verwalten, Spenden zu erfassen und Zuwendungsbestätigungen automatisiert zu erstellen. Das System ist als White-Label-Lösung konzipiert und kann vollständig an das Corporate Design Ihrer Organisation angepasst werden.

1 Installation & Ersteinrichtung

Systemvoraussetzungen

Bevor Sie mit der Installation beginnen, stellen Sie sicher, dass Ihr Server die folgenden Mindestanforderungen erfüllt:

Download & Dateistruktur

Nach dem Entpacken des Archivs finden Sie folgende Verzeichnisstruktur im Hauptordner foerderportal/:

foerderportal/
├── index.php              # Einziger Einstiegspunkt (Single Entry Point)
├── setup.php              # Ersteinrichtungsassistent (danach absichern!)
├── .htaccess              # Apache URL-Rewriting + Sicherheitsregeln
├── nginx-security.conf    # Nginx-Konfigurationsblock zum Einbinden
│
├── includes/              # PHP-Kernlogik
│   ├── database.php       # PDO/SQLite-Singleton mit Hilfsmethoden
│   ├── auth.php           # Session-Auth + TOTP 2FA
│   ├── functions.php      # XSS-Schutz e(), CSRF, sendSMTPEmail()
│   ├── admin.php          # Adminbereich-Controller (~800 Zeilen)
│   ├── frontend.php       # Öffentliche Routen
│   ├── pdf_generator.php  # Antrags-PDF (FPDF)
│   ├── bescheid_generator.php  # Förderbescheid-PDF
│   └── receipt_generator.php   # Zuwendungsbestätigung-PDF
│
├── templates/             # PHP-HTML-Templates
│   ├── admin/             # Admin-Oberfläche
│   └── frontend/          # Öffentliche Seiten
│
├── api/
│   └── handler.php        # REST-API-Endpunkte
│
├── cron/
│   └── run.php            # Cron-Job für E-Mail-Automatisierung
│
├── assets/                # CSS, JS, Bilder
│
├── data/                  # Datenbankdatei + Uploads (Schreibrecht nötig!)
│   ├── database.sqlite    # SQLite-Datenbank (nach Setup erstellt)
│   ├── logo.png / logo.jpg
│   └── unterschrift_1.png … unterschrift_5.png
│
└── config/
    └── config.php         # Auto-generiert durch Setup (NICHT einchecken!)

Dateirechte setzen

Die Verzeichnisse config/ und data/ müssen vom Webserver beschreibbar sein. Setzen Sie die Berechtigungen nach dem Upload:

# Verzeichnisse für Webserver-Benutzer schreibbar machen
chmod 755 config/ data/

# Falls nötig: Besitzer auf Webserver-User setzen (z.B. www-data bei Apache/Ubuntu)
chown -R www-data:www-data config/ data/

# Alternativ mit ACL (empfohlen auf Shared Hosting)
setfacl -R -m u:www-data:rwx config/ data/

Setup-Assistent (setup.php)

Der einmalige Setup-Assistent initialisiert die SQLite-Datenbank und legt den ersten Administrator-Account an. Rufen Sie nach dem Upload die folgende URL im Browser auf:

https://ihre-domain.de/setup.php

TOTP 2FA einrichten

Beim ersten Login nach dem Setup wird der Administrator automatisch zur Einrichtung der Zwei-Faktor-Authentifizierung (2FA) weitergeleitet. Das System verwendet TOTP (Time-based One-Time Password) nach RFC 6238 – kompatibel mit Google Authenticator, Microsoft Authenticator und allen gängigen TOTP-Apps.

Hosting-Konfiguration

Apache VirtualHost

Erstellen Sie eine neue VirtualHost-Konfiguration unter /etc/apache2/sites-available/foerderportal.conf:

<VirtualHost *:443>
    ServerName  portal.ihre-stiftung.de
    DocumentRoot /var/www/foerderportal

    <Directory /var/www/foerderportal>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    # Zugriff auf sensitive Verzeichnisse sperren
    <Directory /var/www/foerderportal/data>
        Require all denied
    </Directory>
    <Directory /var/www/foerderportal/config>
        Require all denied
    </Directory>

    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/portal.ihre-stiftung.de/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/portal.ihre-stiftung.de/privkey.pem
</VirtualHost>

# HTTP → HTTPS Weiterleitung
<VirtualHost *:80>
    ServerName portal.ihre-stiftung.de
    Redirect permanent / https://portal.ihre-stiftung.de/
</VirtualHost>

Aktivieren Sie den VirtualHost und starten Sie Apache neu:

a2ensite foerderportal.conf
a2enmod rewrite ssl
systemctl restart apache2

Nginx Konfiguration

Binden Sie die mitgelieferte Datei nginx-security.conf in Ihren Server-Block ein:

server {
    listen 443 ssl;
    server_name portal.ihre-stiftung.de;
    root /var/www/foerderportal;
    index index.php;

    # Sicherheitskonfiguration einbinden
    include /var/www/foerderportal/nginx-security.conf;

    # URL-Rewriting für Single-Entry-Point
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # Sensitive Verzeichnisse sperren
    location ~* ^/(data|config)/ {
        deny all;
        return 403;
    }

    # PHP-FPM
    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    ssl_certificate     /etc/letsencrypt/live/portal.ihre-stiftung.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/portal.ihre-stiftung.de/privkey.pem;
}

2 Einstellungen

Die Einstellungen sind im Adminbereich unter Einstellungen in sechs Tabs gegliedert. Alle Werte werden in der Tabelle settings als Schlüssel-Wert-Paare gespeichert und sofort wirksam.

E-Mail & SMTP konfigurieren

Das System versendet E-Mails über SMTP (empfohlen) oder als Fallback über die PHP-Funktion mail(). Konfigurieren Sie SMTP unter Einstellungen → E-Mail:

E-Mail-Vorlagen & Platzhalter

Unter Einstellungen → E-Mail-Vorlagen können Sie die automatisch versendeten E-Mails individuell anpassen. Jede Vorlage hat einen Betreff und einen HTML/Text-Körper. Folgende Platzhalter werden beim Versand durch die echten Werte ersetzt:

Beispiel: Bewilligungsmail

Betreff: Ihr Förderantrag {{antragsnummer}} wurde bewilligt

Sehr geehrte/r {{name}},

wir freuen uns, Ihnen mitteilen zu können, dass Ihr Förderantrag
für das Projekt „{{projekt}}" in unserer Vorstandssitzung positiv
beschieden wurde.

Bewilligter Förderbetrag: {{betrag}}
Antragsnummer: {{antragsnummer}}
Projektzeitraum: {{projektstart}} bis {{projektende}}

Den offiziellen Förderbescheid finden Sie im Anhang dieser E-Mail.

Mit freundlichen Grüßen
Ihr Team der {{organisation}}

Automatisierung & Cron-Jobs

Das System sendet automatische Erinnerungs-E-Mails vor Projektbeginn und nach Projektende. Diese Funktion erfordert einen eingerichteten Cron-Job.

Option 1: Server-Crontab (empfohlen)

# Crontab bearbeiten:
crontab -e

# Täglich um 08:00 Uhr ausführen:
0 8 * * * php /var/www/foerderportal/cron/run.php >> /var/log/foerderportal-cron.log 2>&1

Option 2: Web-Trigger (für Shared Hosting)

Falls kein SSH-Zugriff verfügbar ist, kann der Cron-Job über eine URL ausgelöst werden. Der Sicherheitsschlüssel wird unter Einstellungen → Automatisierung → Cron-Key angezeigt:

GET https://ihre-domain.de/index.php?page=cron&key=IHR_CRON_KEY

Option 3: Manuell über das Dashboard

Unter Dashboard → Automatisierung finden Sie einen Button zum manuellen Auslösen des Cron-Laufs. Dies ist nützlich zum Testen und für ad-hoc Benachrichtigungen.

Dokumente-Tab

Im Reiter Dokumente konfigurieren Sie die Texte und Signaturen für automatisch generierte PDFs:

Förderbescheid-Texte

Passen Sie den Einleitungstext, die Bewilligungsformulierung, Bedingungen und die Schlussformel des Förderbescheids individuell an. Diese Texte werden 1:1 im PDF ausgegeben — Zeilenumbrüche werden berücksichtigt.

Unterschriften hochladen

Das System unterstützt bis zu 5 Unterschriften für Förderbescheide und Zuwendungsbestätigungen. Hochgeladene Bilder werden unter data/unterschrift_1.png bis data/unterschrift_5.png gespeichert.

• Empfohlenes Format: PNG mit transparentem Hintergrund, 300 DPI
• Empfohlene Größe: ca. 400 × 150 Pixel
• Maximale Dateigröße: 2 MB pro Unterschrift
• Zugelassene Formate: PNG, JPG

Integration & API

Unter Einstellungen → Integration verwalten Sie die Schnittstellen zu externen Diensten.

API-Zugangsdaten

Generieren Sie unter diesem Tab einen API-Key und API-Secret für die Nutzung der REST-Schnittstelle. Diese Zugangsdaten werden ausschließlich als HTTP-Header übertragen:

X-API-Key: ihr_api_key
X-API-Secret: ihr_api_secret

Rate Limiting

Die API ist auf 60 Anfragen pro Minute pro IP-Adresse begrenzt. Bei Überschreitung antwortet die API mit HTTP 429 (Too Many Requests). Zähler werden in der Tabelle rate_limit gespeichert und minütlich zurückgesetzt.

Design & Branding

Unter Einstellungen → Design passen Sie das Erscheinungsbild des Portals an Ihre Organisation an. Alle Änderungen werden als CSS-Variablen zur Laufzeit injiziert — kein Neustart erforderlich.

System & Lizenz

Lizenz aktivieren

Rollen & Rechte

3 Arbeitsprozesse

Förderanträge – Workflow

Der Lebenszyklus eines Förderantrags durchläuft definierte Status-Stufen. Der aktuelle Status bestimmt, welche Aktionen verfügbar sind und welche E-Mails automatisch versendet werden.

Typischer Workflow

Digitale Signatur (OTP-Link)

Für bestimmte Fördertypen kann eine digitale Bestätigung durch den Antragsteller angefordert werden. Das System versendet einen signierten E-Mail-Link mit einem Einmal-OTP. Nach Klick und Bestätigung wird die Signatur mit Zeitstempel in der Datenbank gespeichert.

Vorstandssitzungen

Vorstandssitzungen bündeln mehrere Förderanträge für gemeinsame Beratung und Beschlussfassung.

Spendenverwaltung

Das Spendenmodul verwaltet einmalige und wiederkehrende Spenden mit optionalem SEPA-Lastschriftmandat.

Spende erfassen

Zahlungen buchen

Wiederkehrende Spenden erzeugen automatisch Zahlungserwartungen (in der Tabelle donation_payments). Der Schatzmeister bucht eingegangene Zahlungen als „bezahlt" und kann ausbleibende Zahlungen als „fehlgeschlagen" markieren.

Zuwendungsbestätigung (Zuwendungsbescheinigung)

Das System generiert steuerlich anerkannte Zuwendungsbestätigungen nach amtlichem Muster als PDF-Dokument.

Statistiken & Berichte

Das Dashboard bietet interaktive Diagramme über Chart.js:

• Antragsstatistik: Neue Anträge pro Monat, Status-Verteilung, Bewilligungsquote
• Finanzübersicht: Bewilligte Förderbeträge nach Monat/Jahr, Gesamtvolumen
• Spendenstatistik: Spendeneingang nach Turnus und Zeitraum, Neugewinnung vs. Bestandsspender
• E-Mail-Status: Zustellquote, Fehler im E-Mail-Log

4 Technische Referenz

API-Referenz

Die REST-API ermöglicht die Integration mit externen Formularsystemen (FluentForms), Automatisierungsplattformen (z.B. n8n) und eigenen Anwendungen. Die Basis-URL lautet: https://ihre-domain.de/index.php

curl -X POST https://ihre-domain.de/index.php?page=api&action=import \
  -H "X-API-Key: ihr_api_key" \
  -H "X-API-Secret: ihr_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "input_organisation": "Sportverein Musterstadt e.V.",
    "first_name": "Maria",
    "last_name": "Muster",
    "email": "maria@sportverein.de",
    "address_line_1": "Sportplatzweg 1",
    "city": "Musterstadt",
    "zip": "12345",
    "description_projekt": "Neubau Jugendraum",
    "projektdauer": "2025-04-01",
    "projektdauer_1": "2025-09-30",
    "numeric_field_gesamtkosten": "15000",
    "numeric_field_foerderbetrag": "5000",
    "dropdown": "Ja",
    "input_text_kontoinhaber": "Sportverein Musterstadt e.V.",
    "input_mask_IBAN": "DE89370400440532013000",
    "input_mask_bic": "COBADEFFXXX",
    "input_text_institut": "Commerzbank"
  }'

{
  "success": true,
  "id": 42,
  "antragsnummer": "DEMO-2025-000042",
  "message": "Antrag erfolgreich importiert"
}

curl "https://ihre-domain.de/index.php?page=api&action=status&antragsnummer=DEMO-2025-000042"

curl "https://ihre-domain.de/index.php?page=api&action=applications&status=bewilligt&year=2025" \
  -H "X-API-Key: ihr_api_key" \
  -H "X-API-Secret: ihr_api_secret"

curl -X POST "https://ihre-domain.de/index.php?page=api&action=webhook" \
  -H "X-API-Key: ihr_api_key" \
  -H "X-API-Secret: ihr_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"antragsnummer": "DEMO-2025-000042", "event": "payment_confirmed", "amount": 5000}'

Externe Formular- & Webhook-Integration

Die empfohlene Integrationsarchitektur: FluentForms (WordPress) → Automatisierungsplattform (z.B. n8n) (Webhook/HTTP Request Node) → StiftOS API.

Cron-Job Referenz

Das Cron-Skript cron/run.php übernimmt folgende Aufgaben:

• Erinnerungs-E-Mails vor Projektbeginn (konfigurierbare Tage vorab)
• Erinnerungs-E-Mails nach Projektende (für Nachweispflichten)
• Lizenz-Revalidierung (tägliche Lizenzprüfung)
• Rate-Limit-Tabelle aufräumen (alte Einträge löschen)

# Manuelle Ausführung (mit Ausgabe)
php /var/www/foerderportal/cron/run.php

# Crontab-Eintrag: täglich 08:00 Uhr, Ausgabe in Logdatei
0 8 * * * php /var/www/foerderportal/cron/run.php >> /var/log/foerderportal.log 2>&1

# Web-Trigger mit Sicherheitsschlüssel (für Shared Hosting)
# GET https://ihre-domain.de/index.php?page=cron&key=SHA256_KEY

PDF-System (FPDF)

Das System nutzt die FPDF-Bibliothek für die PDF-Generierung. FPDF wird beim ersten Bedarf automatisch von fpdf.org heruntergeladen und mit einem SHA-256-Prüfwert verifiziert. Kein manueller Download erforderlich.

Download-Links werden mit hash_equals() für timing-sicheren SHA256-Token-Vergleich verifiziert. Dies verhindert Timing-Angriffe bei der Token-Validierung.

Datenbankstruktur

Die SQLite-Datenbank liegt unter data/database.sqlite. Das Schema wird beim Setup automatisch erstellt — es gibt kein separates Migrations-Tooling.

Sicherheitsarchitektur

Backup & Wiederherstellung

Das gesamte System lässt sich mit zwei Pfaden vollständig sichern:

# Backup: SQLite-Datenbank + Uploads sichern
DATUM=$(date +%Y%m%d_%H%M%S)
cp /var/www/foerderportal/data/database.sqlite /backup/foerderportal-db-$DATUM.sqlite
tar -czf /backup/foerderportal-data-$DATUM.tar.gz /var/www/foerderportal/data/

# Vollständiges Backup (inkl. Code)
tar -czf /backup/foerderportal-full-$DATUM.tar.gz /var/www/foerderportal/

# Wiederherstellung
cp /backup/foerderportal-db-20250101_080000.sqlite /var/www/foerderportal/data/database.sqlite
chown www-data:www-data /var/www/foerderportal/data/database.sqlite

Troubleshooting & FAQ

1. Setup.php zeigt „PDO SQLite Extension nicht gefunden"

Ursache: Die PHP-Extension pdo_sqlite ist nicht geladen.
Lösung: Führen Sie php -m | grep pdo_sqlite aus. Falls leer, installieren Sie die Extension: apt install php8.3-sqlite3 (Ubuntu) oder aktivieren Sie extension=pdo_sqlite in der php.ini.

2. E-Mails werden nicht versandt / SMTP-Fehler

Ursache: Falsche SMTP-Einstellungen, Firewall blockiert Port 587, oder SSL-Zertifikat-Problem.
Lösung: Prüfen Sie die Einstellungen über Test-E-Mail senden. Schauen Sie in den E-Mail-Log unter Protokolle → E-Mail für genaue Fehlermeldungen. Stellen Sie sicher, dass Ihr Server ausgehende Verbindungen auf Port 587/465 erlaubt.

3. PDF-Generierung schlägt fehl (Blank Page / Error)

Ursache: FPDF konnte nicht heruntergeladen werden, oder Schreibrecht auf temp-Verzeichnis fehlt.
Lösung: Prüfen Sie, ob allow_url_fopen = On in der php.ini gesetzt ist. Laden Sie FPDF manuell herunter und platzieren Sie es unter includes/fpdf/fpdf.php. Prüfen Sie sys_get_temp_dir() auf Schreibbarkeit.

4. TOTP-Code wird nicht akzeptiert

Ursache: Serverzeit weicht stark von der Smartphone-Zeit ab (TOTP ist zeitbasiert).
Lösung: Synchronisieren Sie die Serverzeit: ntpdate -u pool.ntp.org oder aktivieren Sie systemd-timesyncd. Abweichungen bis ±30 Sekunden werden toleriert.

5. API antwortet mit „401 Unauthorized"

Ursache: API-Key oder Secret fehlt, oder wurde als URL-Parameter statt Header übergeben.
Lösung: Stellen Sie sicher, dass X-API-Key und X-API-Secret als HTTP-Request-Header gesetzt sind. URL-Parameter werden aus Sicherheitsgründen nicht akzeptiert.

6. „403 Forbidden" beim Zugriff auf /data/ oder /config/

Ursache: Diese Verzeichnisse sind bewusst gesperrt — das ist korrekt.
Lösung: Der direkte Webzugriff auf diese Verzeichnisse ist aus Sicherheitsgründen geblockt. Greifen Sie auf die Daten ausschließlich über die Anwendung zu.

7. Cron-Job sendet keine E-Mails

Ursache: PHP-Pfad in der Crontab falsch, oder fehlende Berechtigungen.
Lösung: Testen Sie manuell: php /var/www/foerderportal/cron/run.php. Prüfen Sie den PHP-Pfad mit which php. Führen Sie den Cron-Job als denselben User aus wie den Webserver (z.B. www-data).

8. Datenbank wächst sehr schnell

Ursache: Der E-Mail-Log und Audit-Log akkumulieren über Zeit viele Einträge.
Lösung: Führen Sie regelmäßig sqlite3 data/database.sqlite "DELETE FROM email_log WHERE sent_at < datetime('now', '-365 days')" aus. Komprimieren Sie danach mit VACUUM.

9. „Weiße Seite" nach Update

Ursache: PHP-Fehler bei Syntaxfehler in aktualisierten Dateien, oder fehlende Extension.
Lösung: Aktivieren Sie temporär Fehlerausgabe: display_errors = On in php.ini. Prüfen Sie das PHP-Error-Log (error_log-Pfad in phpinfo). Testen Sie Syntax: php -l includes/admin.php.

10. Lizenzaktivierung schlägt fehl

Ursache: Keine Internetverbindung vom Server, falscher Lizenzschlüssel, oder Lizenz bereits auf anderem Server aktiviert.
Lösung: Prüfen Sie, ob der Server ausgehende HTTPS-Anfragen stellen kann: . Kontaktieren Sie den Support mit Ihrer Bestellnummer, wenn die Lizenz auf einem anderen Server deaktiviert werden soll.

11. Förderantrag aus FluentForms wird nicht importiert

Ursache: Mapping in der Automatisierungsplattform falsch konfiguriert, oder falsche Content-Type-Header.
Lösung: Aktivieren Sie das Execution-Log in Ihrer Automatisierungsplattform (z.B. n8n) und prüfen Sie den genauen Request-Body. Stellen Sie sicher, dass Content-Type: application/json gesetzt ist. Testen Sie mit dem curl-Beispiel aus dieser Dokumentation.

12. .htaccess Fehler / 500 Internal Server Error

Ursache: Apache-Modul mod_rewrite ist nicht aktiviert, oder AllowOverride All fehlt.
Lösung: Aktivieren Sie mod_rewrite: a2enmod rewrite && systemctl restart apache2. Stellen Sie in der VirtualHost-Konfiguration AllowOverride All für das Dokumenten-Verzeichnis sicher.