Steuerkram/README.md

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.

Lizenz

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