Vereo

Schlanke, eigenständige Vereinsverwaltung — eine Instanz pro Verein, self-hosted, kostenlos für nutzende Vereine.

Konzept, Grundsätze und Scope: siehe DECISIONS.md und SCOPE.md. Bitte vor dem Mitarbeiten lesen.

Schnellstart (lokal/Test)

Drei Schritte – läuft direkt im Browser (App + Worker + PostgreSQL):

cp .env.example .env
docker compose -f docker-compose.yml -f docker-compose.quickstart.yml up -d
# Danach: http://localhost:8080

• Anmeldung als Administrator: Das initiale Passwort steht im App-Log (docker compose logs app | grep Initial-Passwort), sofern ADMIN_EMAIL/ ADMIN_PASSWORD in der .env nicht gesetzt sind. Standard-Login ist dann admin@vereo.local.
• APP_KEY darf leer bleiben – er wird beim ersten Start erzeugt und im Storage-Volume persistiert (stabil über Neustarts).
• Port änderbar über QUICKSTART_PORT in der .env (Standard 8080).
• Migrationen, RBAC, Admin und Grundkonfiguration richtet der Container beim ersten Start automatisch ein.

Produktion: Hinter Coolify/Traefik ohne das Quickstart-Overlay starten (nur docker-compose.yml); dort übernimmt der Reverse-Proxy Port/TLS, und APP_KEY sollte fest in der Umgebung gesetzt werden.

Updates & Betrieb: Aktualisieren einer laufenden Instanz, Versions-Check und Fehlersuche bei „Update lädt nicht" siehe Deployment & Betrieb.

Dokumentation

Eine ausführliche Bedien- und Betriebsdokumentation liegt unter docs/ – u. a. Beiträge, SEPA-Lastschrift inkl. Testfunktion, Self-Service & Portal, Spenden, Veranstaltungen, Mitteilungen & Newsletter, Rechnungen & Steuer und Dokumentvorlagen/PDF & E-Mail.

Stack

• Laravel (PHP) + Filament (Admin-UI)
• PostgreSQL
• Jobs/Scheduler über Laravel (DB-Queue-Driver, kein Redis im Standard)
• Deploy über Docker / Coolify

Begründung der Wahl (Zuverlässigkeit & Langlebigkeit, wenige bewegliche Teile): siehe DECISIONS.md → Tech-Stack.

Leitplanken (Kurzfassung)

• Single-Tenant: eine Instanz = ein Verein. Keine Mandantentrennung.
• Unabhängig & datensouverän: Betreiber sieht nicht in Vereinsdaten; Instanz ist eigenständig betreibbar.
• Marginaler Wartungsaufwand ≈ 0: Migrations & Admin-Provisioning automatisch beim Start; Backups & Health je Instanz.
• 12-Factor: alles über Env-Variablen; keine festen Ports; Reverse-Proxy-bewusst.

Funktionsumfang

Vereo ist eine vollständige Vereinsverwaltung. Wesentliche Module:

• Mitglieder & CRM: Mitglieder, Konten und Personen, Ansprechpartner mit Funktionen/Rollen, eigene Felder (Custom Fields), CSV-Import/-Export, Serienbrief-Adressexport, Mitglieds-Stammblatt (PDF), 360°-Blick je Mitglied.
• Beiträge & SEPA: Beitragsmodelle, Sollstellung (Jahreslauf mit Vorschau, Einzel- und Sammel-Sollstellung), SEPA-Lastschrift-Lauf, Rücklastschrift, Mahnwesen, Beitragsbescheinigung & -quittung (PDF, einzeln und als Jahres-ZIP).
• Rechnungen: Rechnungsstellung mit GoBD-Nummernkreis, PDF inkl. ZUGFeRD, Mahnautomatik, Versand per E-Mail.
• Veranstaltungen: Events mit Kapazität/Warteliste, öffentliche und Portal- Anmeldung (einbettbar), Teilnehmerlisten (PDF/CSV), Anmelde-Benachrichtigung.
• Self-Service-Portal: Login für Kontakte, Profil-/Kontodaten-Pflege, Event-An-/Abmeldung, Belege (Rechnungen, Beitragsbescheinigungen, freigegebene Dokumente), Übersichts-Dashboard.
• Newsletter: Segmente, Double-Opt-in mit Anmeldeformular (einbettbar), Abmeldung/Opt-out, Abonnenten-Verwaltung, Versand über die Queue.
• Spenden: Erfassung (Mitglied oder extern), Zuwendungsbestätigung (§ 10b EStG, einzeln und als Jahres-Sammelbestätigung), Dankesmail, Import/Export.
• Dashboards: Kennzahlen-Kacheln und Diagramme (Mitgliederentwicklung, Beitrags- und Spendeneinnahmen).
• Auswertungen/Export: Offene-Posten-Liste, Jahresabschluss-Export (ZIP), globale Suche, Audit-Log mit Filtern.

Lokales Setup

cp .env.example .env
# Container bauen & starten
docker compose up -d --build
# Migrations, RBAC und Konfigurationslisten laufen automatisch über den Entrypoint

Deploy via Coolify

• Repo als Quelle, docker-compose.yml verwenden.
• APP_URL auf die externe Domain/Subdomain setzen — wird respektiert, damit Cookies, Redirects, absolute Links und OIDC-Redirects funktionieren.
• Routing/TLS macht Coolify/Traefik. Die App bindet keine festen Host-Ports.
• Persistente Daten liegen in Volumes (DB + hochgeladene Dokumente).

Konfiguration pro Verein (wichtig)

Jede Instanz gehört genau einem Verein. Mindestens setzen:

• APP_URL — die externe HTTPS-Adresse der Instanz.
• ADMIN_EMAIL / ADMIN_PASSWORD — initialer Admin (ohne Passwort wird eines generiert und einmalig ins Container-Log geschrieben).
• ORG_NAME (+ optional ORG_ADDRESS, ORG_ZIP_CITY) — Branding/PDF.

Für den SEPA-Lastschrift-Lauf zusätzlich (Daten des einziehenden Vereins):

• SEPA_CREDITOR_NAME — Vereinsname.
• SEPA_CREDITOR_IBAN — Konto, von dem eingezogen wird.
• SEPA_CREDITOR_ID — Gläubiger-Identifikationsnummer (Format DE…ZZZ…), bei der Deutschen Bundesbank zu beantragen.
• SEPA_CREDITOR_BIC — optional.

Ohne die SEPA_CREDITOR_*-Werte stoppt der SEPA-Knopf bewusst mit einem Hinweis, statt eine unbrauchbare Datei zu erzeugen.

Rollen & Rechte

Zugriffe werden über Berechtigungen (spatie/permission) gesteuert. Die Rolle super_admin umgeht alle Prüfungen. Vorhandene Berechtigungen:

• Mitglieder verwalten
• Finanzen verwalten
• Veranstaltungen verwalten
• Newsletter versenden
• Benutzer verwalten
• Audit-Log einsehen

Geplante Aufgaben (Scheduler)

Beim Containerstart aktiv (über den Laravel-Scheduler, gesteuert per Einstellungen unter Konfiguration → Automatik):

• vereo:contributions-run — Beitrags-Sollstellung
• vereo:sepa-run — SEPA-Lastschrift-Lauf
• vereo:invoice-dunning-run — Rechnungs-Mahnungen
• vereo:dunning-run — Beitrags-Mahnungen

Wartungsbefehle

• php artisan vereo:ensure-rbac — Berechtigungen/Rollen sicherstellen
• php artisan vereo:ensure-config — Konfigurationslisten (Lookups) sicherstellen

Beide laufen automatisch über den Entrypoint und sind idempotent.

Versionierung

Es gilt Semantic Versioning; Änderungen werden in CHANGELOG.md nach dem Format Keep a Changelog gepflegt. Die laufende Version steht in config/vereo.php (version) und erscheint im Footer.