Node-K Management

Vereinsverwaltung und Buchhaltung für den Verein Node-K.

Features

• Mitgliederverwaltung (Selfservice + Admin)
• Buchhaltung via hledger (Web-UI + SSH-Fallback)
• Authentifizierung über authentik (OIDC)
• Rollenbasiertes Berechtigungsmanagement
• Automatische Mitgliedsbeitragsverbuchung
• Vollständiges Audit-Log
• Git-versionierte Finanzdaten

Technologiestack

• Backend: Java 25, Spring Boot 4.0.6, PostgreSQL, Flyway, JGit
• Frontend: Angular 21 (zoneless, signals, standalone), Bootstrap 5 (dark theme)
• Auth: authentik (OAuth2/OIDC)
• Buchhaltung: hledger
• Deployment: Docker (multi-stage build)

Dokumentation für AI-Agents

• .agent.md — Vollständige Architektur-Referenz (Struktur, Flows, Tech Stack)
• .github/copilot-instructions.md — Code-Konventionen und Pflicht zur Doku-Aktualisierung

---

Projektstruktur

├── backend/                Spring Boot Anwendung (Java 25)
│   └── src/main/resources/
│       └── db/migration/   Flyway SQL-Migrationen
├── frontend/               Angular SPA
├── docker/                 Produktions-Docker-Konfiguration
│   ├── Dockerfile          Multi-stage Build (Frontend → Backend → Runtime)
│   ├── entrypoint.sh       Container-Startskript
│   ├── sshd_config         SSH-Konfiguration für hledger-Zugang
│   └── hledger-shell.sh    Restricted Shell für SSH-User
├── docker-compose.yml      Produktion: App + PostgreSQL
└── docker-compose.dev.yml  Entwicklung: Abhängigkeiten (authentik, PostgreSQL, Redis)

Wozu ist was?

Datei	Zweck
docker-compose.yml	Produktionsstack: Management-App + eigene PostgreSQL-Datenbank
docker-compose.dev.yml	Entwicklungs-Abhängigkeiten: authentik (OIDC), Redis, PostgreSQL für authentik, PostgreSQL für Management
docker-compose.test.yml	Vollständiger Image-Test vor Deployment: App-Image wird gebaut + alle Abhängigkeiten
docker/Dockerfile	Multi-stage Build: 1. Angular bauen, 2. Maven-Build, 3. Runtime-Image mit hledger + SSH

---

Lokale Entwicklung

Voraussetzungen

• Java 25 (JDK)
• Maven 3.9+
• Node.js 22+
• Docker Desktop

Schritt 1 — Abhängigkeiten starten

Startet PostgreSQL (für Management-App und authentik), Redis und authentik:

docker compose -f docker-compose.dev.yml up -d

Service	URL / Port
authentik	http://localhost:9000
PostgreSQL (Management)	localhost:5432
PostgreSQL (authentik)	intern, kein Port nach außen

Erster Start: authentik startet mit Bootstrap-Credentials: User akadmin, Passwort admin12345. Anwendung node-k-management danach unter http://localhost:9000 einrichten. Siehe docker/authentik-setup.md.

Schritt 2 — Backend starten

cd backend
mvn spring-boot:run

Das dev-Profil ist standardmäßig aktiv (via application-dev.yml). Das Backend startet auf http://localhost:8080 und führt Flyway-Migrationen automatisch aus.

Benötigte Umgebungsvariablen (z.B. in .env oder IDE-Konfiguration):

AUTHENTIK_CLIENT_ID=<OAuth2 Client ID aus authentik>
AUTHENTIK_CLIENT_SECRET=<OAuth2 Client Secret aus authentik>
AUTHENTIK_ISSUER_URI=http://localhost:9000/application/o/node-k-management/
AUTHENTIK_API_TOKEN=<Service Account Token aus authentik>

Schritt 3 — Frontend starten

cd frontend
npm install   # nur beim ersten Mal
npm start

Das Frontend startet auf http://localhost:4200 und leitet API-Requests per Proxy an http://localhost:8080 weiter.

Entwicklung stoppen

docker compose -f docker-compose.dev.yml down

---

Image-Test vor Deployment

Baut das Docker-Image und startet den vollständigen Stack lokal — inklusive Management-Container, authentik, PostgreSQL und Redis:

docker compose -f docker-compose.test.yml up --build

Service	URL
Management-App	http://localhost:8080
authentik	http://localhost:9000

Stoppen und aufräumen:

docker compose -f docker-compose.test.yml down -v

---

Produktion bauen & deployen

Docker-Image bauen

Der docker/Dockerfile baut in drei Stages:

1. Frontend: npm ci && ng build --configuration production
2. Backend: Maven-Build, statische Frontend-Dateien werden eingebettet
3. Runtime: JRE + hledger + OpenSSH, minimales Image

docker build -t node-k/management:latest -f docker/Dockerfile .

Produktionsstack starten

# .env mit Produktionswerten erstellen (siehe Umgebungsvariablen unten)
docker compose up -d

---

Umgebungsvariablen

Backend (beide Profile)

Variable	Beschreibung
AUTHENTIK_ISSUER_URI	OIDC Issuer URI (z.B. https://auth.example.com/application/o/management/)
AUTHENTIK_CLIENT_ID	OAuth2 Client ID
AUTHENTIK_CLIENT_SECRET	OAuth2 Client Secret
AUTHENTIK_BASE_URL	authentik Base URL für API-Calls
AUTHENTIK_API_TOKEN	API Token für den Service Account
GIT_REPO_URL	Forgejo/Git Repository URL
GIT_SSH_KEY_PATH	Pfad zum Deploy Key (nur Docker: /data/ssh/git_deploy_key)

Nur Produktion (docker-Profil)

Variable	Beschreibung
DB_HOST	PostgreSQL-Host (Standard: postgres-management)
DB_NAME	Datenbankname (Standard: management)
DB_USERNAME	Datenbankbenutzer (Standard: management)
DB_PASSWORD	Datenbankpasswort (Pflichtfeld)

---

SSH-Zugang (Kassier)

Der Container stellt einen eingeschränkten SSH-Zugang auf Port 2222 bereit:

ssh -p 2222 hledger@<host>

Erlaubte Befehle: hledger balance|register|print|accounts|check|incomestatement|balancesheet, git pull|status|log|diff, ls, cat (nur im Journal-Verzeichnis).

SSH Public Keys werden über die Management-UI verwaltet und automatisch in authorized_keys geschrieben.

---

Rollen

Rolle	authentik-Gruppe	Berechtigungen
MEMBER	node-k-member	Eigenes Profil bearbeiten
BOARD	node-k-board	Mitgliederliste, Reports
TREASURER	node-k-treasurer	Buchungen, Beiträge, hledger
ADMIN	node-k-admin	Alles + Benutzerverwaltung