entrytwo
kaufen

docs / invoices / getting-started / installation.md

Installation

Invoices ist die selbst gehostete App für Kontakte und KI-gestützte Rechnungen, nicht das entrytwo-Buchhaltungs-Ledger.

Das Quellcode-Repository ist öffentlich. Es gibt kein veröffentlichtes Invoices-Docker-Image. Du baust das enthaltene Dockerfile lokal. GitHub-Konto, Zugriffstoken und Registry-Login sind nicht erforderlich. invoices:latest ist ein lokaler Image-Tag, kein Registry-Download.

Der Code steht unter einer proprietären Source-Available-Lizenz, nicht unter einer Open-Source-Lizenz. Einsehen, Klonen, Bauen und private Änderungen sind im Rahmen der Lizenz erlaubt. Die vollständige App ist 30 Tage kostenlos nutzbar; danach ist eine Invoices-Einmallizenz erforderlich. Ein entrytwo-Buchhaltungs-Key aktiviert Invoices nicht.

Installation mit KI-Unterstützung: Gib deinem Coding-Agenten diese Seite und den Invoices-Installations-Skill. Nenne das Ziel: lokal oder VPS mit Domain. Teile keine Secrets im Chat. Agenten dürfen installieren und konfigurieren; Käufe und Checkout bleiben beim Menschen.

Voraussetzungen

  • Git, Docker und Docker Compose v2 oder neuer (auf macOS: Docker Desktop).
  • Mindestens 2 GB RAM; für den Build auf dem Server sind 4 GB oder mehr sinnvoll.
  • Funktionierendes SMTP und/oder Google-/Microsoft-OAuth für die Anmeldung. Für Rechnungs-E-Mails ist SMTP zusätzlich erforderlich.
  • Für öffentlich erreichbare VPS: eine Domain mit korrektem DNS und ein HTTPS-Reverse-Proxy wie Caddy oder nginx.
  • Optional: eigene KI-Zugangsdaten für Rechnungsentwürfe per Chat.

1. Quellcode klonen

git clone https://github.com/felixkrusch/invoices.git
cd invoices
cp .env.example .env

Halte .env privat. Überschreibe keine bestehende Installationskonfiguration.

2. Umgebung konfigurieren

Erzeuge getrennte Werte und trage sie in .env ein:

openssl rand -base64 48   # AUTH_SECRET
openssl rand -hex 32      # ENCRYPTION_KEY (für spätere Wiederherstellung sichern)
openssl rand -base64 48   # JOB_RUNNER_SECRET
openssl rand -base64 48   # UPDATER_TOKEN
openssl rand -hex 24      # POSTGRES_PASSWORD

AUTH_SECRET und JOB_RUNNER_SECRET brauchen mindestens 32 Zeichen; ENCRYPTION_KEY genau 64 Hex-Zeichen. Compose wertet derzeit auch den optionalen Updater-Service aus. Setze daher UPDATER_TOKEN, obwohl du den Updater nicht aktivierst. Compose bildet die Datenbank-URL aus POSTGRES_PASSWORD; eine PostgreSQL-Installation auf dem Host ist für diesen Weg nicht erforderlich.

Gemeinsame Einstellungen:

APP_IMAGE="invoices:latest"
APP_VERSION="dev"
UPDATER_URL=""
UPDATE_MANIFEST_URL=""
LICENSE_VERIFY_URL="https://entrytwo.com/api/license/verify"
AUTH_TRUST_HOST="true"

Notiere git rev-parse HEAD, um den gebauten Quellstand festzuhalten. Aktiviere weder das Updater-Profil noch einen Update-Feed der entrytwo-Buchhaltungs-App.

Lokale Docker-Installation

Zum Beispiel Port 3001, damit entrytwo auf Port 3000 weiterlaufen kann:

APP_PORT="127.0.0.1:3001"
AUTH_URL="http://localhost:3001"
APP_PUBLIC_URL="http://localhost:3001"
AUTH_ALLOW_HTTP="true"

Docker startet die App auch auf dem Laptop im Produktionsmodus. Echtes SMTP/OAuth und TOTP für Administratoren bleiben erforderlich; der sofortige Entwickler-Login ist nicht verfügbar. AUTH_ALLOW_HTTP=true ist ausschließlich eine Localhost-/Labor-Ausnahme, keine Einstellung für öffentliche Server. Binde den Port wie oben nur an Loopback. Für native Node.js-Entwicklung siehe SETUP.md im Repository.

VPS mit HTTPS

APP_PORT="127.0.0.1:3000"
AUTH_URL="https://invoices.example.com"
APP_PUBLIC_URL="https://invoices.example.com"
AUTH_ALLOW_HTTP="false"

Ersetze die Beispieldomain. DNS muss vor der Zertifikatsanforderung auf den VPS zeigen. Der Proxy leitet HTTPS an 127.0.0.1:3000 weiter und übermittelt den ursprünglichen Host und das HTTPS-Schema. PostgreSQL nicht öffentlich freigeben.

Anmeldung und E-Mail

Konfiguriere SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM und/oder eine vollständige Google-/Microsoft-OAuth-Konfiguration aus .env.example. Registriere beim Anbieter exakt den passenden Callback:

  • {AUTH_URL}/api/auth/callback/google
  • {AUTH_URL}/api/auth/callback/microsoft-entra-id

OAuth allein genügt zur Anmeldung. Für Rechnungs-E-Mails sind SMTP und der Worker erforderlich. Optionale KI-/Zahlungs-Zugangsdaten bleiben leer, wenn du diese Integrationen nicht verwendest.

3. Lokal bauen und starten

Nach der Konfiguration von .env, im geklonten Repository:

docker compose -f compose.yaml pull db
docker compose -f compose.yaml build app
docker compose -f compose.yaml up -d --no-build --pull never app worker db
docker compose -f compose.yaml ps

Nur PostgreSQL wird aus einer öffentlichen Registry geladen. Die App wird lokal gebaut; der Worker nutzt dasselbe lokale Image und startet erst nach dem Build. Kein docker compose pull app worker ausführen. Der Entrypoint wendet die Prisma-Migrationen an.

Für das lokale Beispiel:

curl --fail --silent --show-error http://localhost:3001/api/health

Auf dem VPS prüfst du stattdessen https://deine-domain/api/health. Erst bei "ready": true und "status": "ok" fortfahren. Werte aus .env sind nicht automatisch Shell-Variablen; APP_PORT kann außerdem die Bind-Adresse enthalten. Nutze die echte URL, nicht ${APP_PORT:-3000} in curl-Befehlen.

Bei Startfehlern:

docker compose -f compose.yaml logs --tail=100 app worker

Fehlende Secrets, unvollständiges SMTP/OAuth oder eine HTTP-AUTH_URL ohne explizite lokale Ausnahme verhindern den Produktionsstart. Authentifizierung nicht abschalten und Datenbank-Volumes nicht als Fehlerbehebung löschen.

4. Erste Nutzung und Lizenz

Öffne die konfigurierte URL, lege den ersten ADMIN an, aktiviere TOTP und richte Firma, Steuersätze, Kontakt und Testrechnung ein. Prüfe PDF-Download und E-Mail-Zustellung. Der Worker muss laufen, sonst bleiben E-Mails in der Warteschlange.

Der 30-Tage-Test braucht keinen Key. Ein Mensch kauft unter Invoices kaufen und aktiviert den Invoices-Key im Lizenzdialog der App. Die authentifizierte Aktivierungs-API ist POST /api/license/activate mit {"key":"et1.<payload>.<sig>"}. Die App sendet einmalig product: invoices an den Verifizierungsdienst; die erfolgreiche Aktivierung gilt dauerhaft für diese Installation.

Eine Invoices-Lizenz deckt Installationen für Unternehmen ab, die dir gehören. Jedes Unternehmen bekommt einen eigenen Stack mit eigener Datenbank. Fremde Mandanten benötigen eigene Lizenzen, auch wenn du ihre Server verwaltest.

Backups, Updates und mehrere Firmen

  • Pro Firma: eigenes Verzeichnis, COMPOSE_PROJECT_NAME, Port, Secrets, Datenbank und private Datei-Volumes. Invoices ist nicht mandantenfähig.
  • .invbackup exportieren und extern sichern; den ursprünglichen ENCRYPTION_KEY separat sicher aufbewahren. Nicht mit entrytwo-.etbackup kompatibel. Wiederherstellung auf einer isolierten Installation testen.
  • Kein docker compose down -v: Es löscht persistente Volumes.
  • Updates bedeuten derzeit: Quellstand prüfen, sichern, app neu bauen und App und Worker neu erstellen. Es gibt keinen veröffentlichten Image-Feed für den In-App-Updater. Nutze die Quellcode-Update-Anleitung.

Weitere Betriebsdetails: Produktions-Checkliste und Authentifizierungs-Checkliste.

Volles Ledger? entrytwo-Installation.