techbygiusi/geldstueck-server repository overview

⁠Geldstück Server

Die selbst gehostete REST-API für Geldstück. Sie speichert Benutzer, Kategorien, Buchungen und Monatsbudgets in PostgreSQL und synchronisiert die Web- und Android-App.

⁠Funktionen

• Registrierung und Login
• Passwort-Hashing mit bcrypt
• JWT-Sitzungen
• Einnahmen und Ausgaben
• eigene Kategorien
• Monatsbudgets und Auswertungen
• automatische Datenbankschema-Einrichtung beim Start
• Health-Endpoint für Container und Reverse Proxies

⁠Voraussetzungen

• PostgreSQL 17 oder kompatibel
• ein langes, zufälliges JWT_SECRET
• eine gültige PostgreSQL-Verbindungsadresse in DATABASE_URL

⁠Schnellstart mit Docker Compose

services:
  database:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: geldstueck
      POSTGRES_USER: geldstueck
      POSTGRES_PASSWORD: CHANGE_ME_DATABASE_PASSWORD
    volumes:
      - money-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U geldstueck -d geldstueck"]
      interval: 5s
      timeout: 5s
      retries: 12

  server:
    image: techbygiusi/geldstueck-server:latest
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://geldstueck:CHANGE_ME_DATABASE_PASSWORD@database:5432/geldstueck
      JWT_SECRET: CHANGE_ME_TO_A_LONG_RANDOM_SECRET
      CORS_ORIGIN: https://money.example.de
      PORT: 3000
    depends_on:
      database:
        condition: service_healthy
    ports:
      - "3000:3000"

volumes:
  money-data:

Stack starten:

docker compose up -d

Status prüfen:

curl http://localhost:3000/health

Erwartete Antwort:

{"ok":true,"service":"geldstueck-server"}

⁠Umgebungsvariablen

⁠Endpoints

⁠Web-App

Die passende Oberfläche ist als techbygiusi/geldstueck-web verfügbar. Beim ersten Start dort die öffentlich erreichbare URL dieser API eintragen.

Beim direkten Aufruf der Server-URL erscheint eine responsive Statusseite mit Datenbankzustand, Laufzeit und Link zur Web-App. Das Linkziel wird mit PROJECT_URL konfiguriert.

⁠Updates und Datensicherung

docker compose pull
docker compose up -d

Vor Updates sollte das PostgreSQL-Volume beziehungsweise die Datenbank gesichert werden. Für reproduzierbare Installationen statt latest den Tag 0.1.2 verwenden.

⁠Sicherheit

• API nur über HTTPS öffentlich bereitstellen.
• niemals das Beispielpasswort oder Beispiel-Secret übernehmen.
• CORS_ORIGIN produktiv nicht auf * setzen.
• PostgreSQL nicht direkt ins Internet veröffentlichen.
• regelmäßige Datenbanksicherungen einrichten.
• Unterstützte Plattform des aktuellen Images: linux/amd64.