Zum Inhalt springen
`CTRL K`

# Rapport Server

Self-Hosting

Rapport Server — der vollständige Selfhost-Stack für Rapport. Eigene Daten, eigene Domain, eigener Server. Komplett Open-Source, Docker-Compose, AGPL-3.0.

## Wann brauchst du Rapport Server?

Szenario | Lösung
--- | ---
Ein Mensch, ein Mac | Desktop-App reicht — Installation
Mehrere Personen im Studio | Rapport Server auf einem Mac Mini oder Linux-Server
Verteiltes Team, Home-Office, Mobile-Zugriff | Rapport Server mit Reverse-Proxy + SSL
Cloud-Hosting bei einem Anbieter | Rapport Server auf VPS/Hetzner/etc.

> Die Desktop-App speichert lokal als JSON. Rapport Server bringt Postgres + Multi-User + Realtime-Sync — für alle, die zu zweit oder im Team arbeiten.

## Architektur

Rapport Server bündelt sechs Open-Source-Komponenten zu einem stimmigen Stack:

    ┌──────────────────────────────────────────────────────┐
    │  Browser / Desktop-App                                │
    └──────────────┬───────────────────────┬───────────────┘
                   │                       │
                   ▼                       ▼
            ┌──────────┐            ┌──────────┐
            │  nginx   │            │   Kong   │  ← API-Gateway
            │  (app)   │            │          │
            └──────────┘            └──────────┘
                                          │
                      ┌───────────────────┼─────────────────────┐
                      ▼                   ▼                     ▼
                  ┌────────┐         ┌──────────┐          ┌─────────┐
                  │ GoTrue │         │PostgREST │          │ Realtime│
                  │ (Auth) │         │  (API)   │          │  (WS)   │
                  └────────┘         └──────────┘          └─────────┘
                      │                   │                     │
                      └───────────────────┼─────────────────────┘
                                          ▼
                                ┌─────────────────┐
                                │   PostgreSQL    │
                                └─────────────────┘
                                          │
                                          ▼
                                ┌─────────────────┐
                                │     Storage     │  ← Belege, Logos
                                └─────────────────┘

Komponente | Funktion
--- | ---
PostgreSQL | Datenbank — alle Rapport-Daten
GoTrue | Authentication — Email/Passwort, JWT-Tokens
PostgREST | REST-API direkt aus dem Postgres-Schema
Realtime | WebSocket-Sync für Live-Updates
Storage | Object-Storage für Belege & Logos
Kong | API-Gateway, routet alle Calls
app (nginx) | Liefert das Rapport-Frontend (React-Build)

Alles in einem Docker-Compose. Keine Cloud-Abhängigkeit, keine Telemetrie.

## Voraussetzungen

OS | Container-Runtime
--- | ---
Linux (Ubuntu 22.04+, Debian 12+, …) | Docker Engine + Compose v2
macOS (Mac Mini etc.) | Colima + Docker CLI — voll OSS

> Auf macOS funktionieren auch OrbStack oder Docker Desktop, beide sind aber proprietär. Colima ist die OSS-Alternative und für Selfhost vollkommen ausreichend.

Plus: ein DNS-Name für TLS (z. B. `rapport.studio.ch`), und optional ein Reverse-Proxy wie Nginx Proxy Manager
oder Caddy
.

## Setup in 5 Schritten

### 1 · Repo klonen

    git clone https://git.kgva.ch/karim/rapport-server.git
    cd rapport-server

### 2 · `.env` erstellen

    cp .env.example .env

In `.env` müssen mindestens diese Werte ersetzt werden:

Variable | Was
--- | ---
`POSTGRES_PASSWORD` | DB-Passwort (≥ 32 Zeichen, zufällig)
`JWT_SECRET` | JWT-Signatur (≥ 32 Zeichen, zufällig)
`ANON_KEY` / `SERVICE_ROLE_KEY` | aus JWT-Secret abgeleitet
`SITE_URL` | Public-URL der Instanz (z. B. `https://app.rapport.studio.ch`)

Zufallswerte generieren:

    openssl rand -hex 32   # für POSTGRES_PASSWORD und JWT_SECRET
    node scripts/generate-keys.mjs   # ANON_KEY + SERVICE_ROLE_KEY aus JWT_SECRET

### 3 · Migrations holen

Die SQL-Migrations stammen aus dem App-Repo. Einmal initial holen:

    ./scripts/sync-migrations.sh

Bei späteren Rapport-Updates erneut ausführen, dann `docker compose down && docker compose up -d`.

### 4 · Stack starten

    docker compose up -d

Erststart dauert ~1 Minute (Postgres initialisiert sich, Migrations laufen, Container starten).

### 5 · Health-Check

    docker compose ps

Alle Container sollten `healthy` zeigen. Frontend ist dann erreichbar unter `http://localhost:8080`.

## Reverse-Proxy + HTTPS

Für Production-Setups mit eigener Domain — Caddy ist die einfachste Variante (config-as-code, Let’s-Encrypt automatisch):

    app.rapport.studio.ch {
      reverse_proxy localhost:8080
    }

    api.rapport.studio.ch {
      reverse_proxy localhost:8000
    }

In `.env` dann:

    SITE_URL=https://app.rapport.studio.ch
    API_EXTERNAL_URL=https://api.rapport.studio.ch

Alternativ über Nginx Proxy Manager mit Web-UI — siehe Troubleshooting.

## Updates

    git pull
    ./scripts/sync-migrations.sh   # falls neue SQL-Migrationen
    docker compose pull             # neueste Container-Versionen
    docker compose up -d            # neu starten

Daten bleiben erhalten — das Volume `postgres-data` wird nicht angetastet.

## Backup

### Postgres-Dump

    docker compose exec -T db pg_dumpall -U postgres > backup-$(date +%Y%m%d).sql

Empfohlen: per `cron` täglich + auf externe Disk / S3 / Backblaze sichern.

### Storage (Belege, Logos)

    docker compose exec storage tar -czf - /var/lib/storage > storage-$(date +%Y%m%d).tar.gz

### Restore

    docker compose down
    docker volume rm rapport-server_postgres-data
    docker compose up -d db
    sleep 10
    cat backup-YYYYMMDD.sql | docker compose exec -T db psql -U postgres
    docker compose up -d

## Bezug Rapport ↔ Rapport Server

Komponente | Wo | Lizenz
--- | --- | ---
Rapport Desktop-App | git.kgva.ch/karim/RAPPORT | AGPL-3.0
Rapport Server | git.kgva.ch/karim/rapport-server | AGPL-3.0

Die Desktop-App kann wahlweise im Lokal-Modus (JSON, kein Server nötig) oder im Cloud-Modus (gegen Rapport Server) betrieben werden. Wechsel erfolgt im Login-Bildschirm der App.

## Häufige Fragen

### Brauche ich Supabase Cloud?

Nein. Rapport Server ist die Selfhost-Variante derselben Komponenten (Postgres + GoTrue + PostgREST + Realtime + Storage), aber komplett auf eigener Infrastruktur. Kein Supabase-Account, keine externe Abhängigkeit.

### Kann ich von der Desktop-App auf Rapport Server migrieren?

Im Login der Desktop-App auf Cloud wechseln, Server-URL eingeben, Account erstellen, Daten manuell wieder anlegen (Bürodaten, Mitarbeiter, Kunden). Ein direkter localStorage → Postgres-Import ist geplant
.

### Was kostet das?

Nichts — Rapport Server ist Open-Source (AGPL-3.0). Du brauchst nur einen Server (Mac Mini, NAS, VPS) und ggf. eine Domain.

### Wieviel Server-Resourcen?

Ein Mac Mini M1 (8 GB RAM) reicht problemlos für ein 5-Personen-Studio. Linux-VPS mit 2 GB RAM + 2 CPU reicht auch.

## Quellcode

git.kgva.ch/karim/rapport-server
— Issues, Pull Requests und Forks willkommen.