Steuerkram

Self-hosted Buchhaltungs- und Steueranwendung für deutsche Freiberufler und Kleinunternehmer. Entwickelt als datensouveräne Alternative zu SaaS-Diensten.

Funktionsumfang

• Kontenrahmen SKR03 – vollständiger Kontenrahmen mit ~80 vorbesetzten Konten (CRUD)
• Belegverwaltung – Upload von PDF, PNG, TIFF und ZUGFeRD-XML; SHA-256 Integritätsprüfung
• Buchungen – EÜR-Buchungsmodell (Einnahme/Ausgabe) mit Kategorie- und Zahlungskonto; GoBD-konforme Trigger verhindern nachträgliche Manipulation
• Kundenverwaltung – CRUD
• Ausgangsrechnungen – DIN 5008 Layout, PDF-Export via mPDF
• UStVA – Kennzahlen-Berechnung aus Buchungen, ELSTER XML-Export
• EÜR – Jahresauswertung mit PDF-Export
• Einstellungen – Firmendaten, Logo, ELSTER-Steuernummer
• Benutzerverwaltung – Benutzer anlegen, bearbeiten, deaktivieren und löschen; session-basierte Authentifizierung mit 24 h Timeout

Tech Stack

Dieses Projekt wurden mit Unterstützung von Claude Code entwickelt.

Schicht	Technologie
Webserver	Apache 2.4
Backend	PHP 8.3 (MVC, kein Framework)
Datenbank	MariaDB 11
PDF-Generierung	mPDF 8.x
Frontend	HTML, CSS, JavaScript (keine Bibliotheken)
Deployment	Docker / Docker Compose

Voraussetzungen

• Docker ≥ 24
• Docker Compose ≥ 2.20 (in neueren Docker-Versionen enthalten)
• Git

Installation

Automatische Installation

Das Script install.sh übernimmt die gesamte Installation: es erkennt die Linux-Distribution, installiert git, curl und Docker, klont das Repository in das gewünschte Verzeichnis und legt die .env-Datei an.

Das Script muss vor dem Klonen des Repositories heruntergeladen werden – es erledigt das Klonen selbst:

curl -fsSL https://codeberg.org/fds2610/Steuerkram/raw/branch/main/install.sh -o install.sh
sudo bash install.sh

Das Script muss als root ausgeführt werden, da es Pakete installiert und ggf. den Docker-Dienst aktiviert. Mit sudo bash install.sh funktioniert das ohne dauerhaft als root angemeldet zu sein.

Nach der Installation die .env-Datei im gewählten Installationsverzeichnis anpassen (siehe Hinweis am Ende des Scripts) und anschließend die Container starten:

cd /opt/Steuerkram   # oder das gewählte Verzeichnis
docker compose up -d

---

Manuelle Installation

1. Repository klonen

git clone <repository-url> steuerkram
cd steuerkram

2. Konfiguration anpassen

Kopiere .env.example nach .env und passe die Werte an:

cp .env.example .env

DB_PASS=sicheres-passwort        # Datenbankpasswort – in docker-compose.yml spiegeln
APP_SECRET=zufaelliger-string    # Zufälligen langen String eintragen (für Sessions)

Außerdem in docker-compose.yml das MARIADB_PASSWORD im db-Service auf denselben Wert wie DB_PASS setzen.

3. Container starten

docker compose up -d

Beim ersten Start werden automatisch:

• die Datenbank initialisiert (migrations/001_initial_schema.sql)
• der SKR03-Kontenrahmen eingespielt (migrations/002_seed_skr03.sql)
• das Docker-Image mit PHP-Abhängigkeiten (mPDF) gebaut

4. Anwendung aufrufen

http://localhost:8080

Beim ersten Aufruf erscheint die Ersteinrichtung: dort den ersten Benutzer-Account anlegen. Danach ist die Anwendung passwortgeschützt.

Weitere Benutzer können nach dem Login unter Benutzer in der Seitenleiste verwaltet werden.

5. Firmendaten hinterlegen

Nach dem ersten Login unter Einstellungen Firmendaten, Logo und ELSTER-Steuernummer eintragen. Diese Angaben erscheinen auf Ausgangsrechnungen und im EÜR-Export.

Port ändern

Der Standard-Port ist 8080. Um ihn zu ändern, passe in docker-compose.yml die ports-Zeile an:

ports:
  - "9090:80"   # Beispiel: Port 9090 auf dem Host

Datenpersistenz

Pfad	Inhalt
./data/mariadb/	MariaDB-Datenbankdateien
Docker Volume uploads	Hochgeladene Belege

Beide Pfade liegen außerhalb des Containers und bleiben bei docker compose down erhalten.

Backup

bash scripts/backup.sh

Das Skript erstellt ein Dump der Datenbank sowie ein Archiv der Uploads im Verzeichnis backups/.

Update

git pull
docker compose up -d --build

GoBD-Hinweise

• Gebuchte Sätze können nicht geändert oder gelöscht werden (MariaDB BEFORE UPDATE/DELETE Trigger).
• Korrekturen erfolgen ausschließlich über Stornobuchungen.
• Jeder hochgeladene Beleg erhält einen SHA-256 Hash zur Integritätsprüfung.

Support

Issues können im Codeberg-Repo gemeldet werden. Mit dem Label automate werden sie automatisch verarbeitet.

Automatisierter Agent

Ein stündlich per Cron gestarteter Agent (Claude CLI) verarbeitet Issues mit dem Label automate nacheinander – mit Lockfile-Schutz gegen Parallelläufe. Mehrere offene Tickets werden in einer Sitzung sequenziell abgearbeitet.

Ablauf je Ticket

1. Issue-Body und alle Kommentare laden (inkl. Diskussionsergebnisse früherer Rückfragen)
2. Relevante Codebase-Dateien lesen
3. Klarheitscheck: Sind die Anforderungen eindeutig? Falls nicht → Rückfragen als Kommentar posten, automate-Label entfernen, warten
4. Analyse mit Claude Opus (Ursache, Lösungsplan, Risiken)
5. Lösung implementieren
6. Tests ausführen (php tests/run.php), Fehler beheben
7. Commit & Push: Fix #NR: Kurzbeschreibung
8. Kommentar mit Zusammenfassung im Issue posten
9. Labels aktualisieren, Issue offen lassen

Label-Ausgänge

Ergebnis	automate	gesetztes Label
Erfolgreich umgesetzt	entfernt	testing
Unklar / Rückfrage offen	entfernt	(keins)
Zu riskant / abgelehnt	entfernt	abgelehnt

Lizenz

Dieses Projekt steht unter der MIT-Lizenz – siehe LICENSE.md für Details.