entrytwo
kaufen

docs / getting-started / installation.md

Installation

Diese Anleitung bringt eine selbst gehostete entrytwo-Instanz zum Laufen.

entrytwo ist KI-native doppelte Buchführung mit Git-ähnlichem Datenmodell. Die KI bucht echte Journalbuchungen bei hoher Sicherheit. Vollständige Historie, Branches, Blame. Self-hosted.

Betrieb: Die meisten Produktions-Setups nutzen einen VPS mit Docker und HTTPS. Du kannst genauso lokal installieren und produktiv nutzen (z. B. auf dem Mac): dieselbe volle App, wie klassische Buchhaltungssoftware ohne Cloud. Läuft auf deinem VPS oder lokal.

Lass die KI die Installation machen

Kein Terminal-Mensch? Du kannst entrytwo trotzdem installieren. Gib einem KI-Coding-Agenten diese Seite (und das Repo) und bitte ihn, die Installation für dich zu erledigen — z. B. Claude Code, OpenClaw, Hermes, Cursor oder ein vergleichbares Tool, das Befehle auf deinem Rechner oder VPS ausführen kann. Sag ihm dein Ziel (lokal Mac vs. VPS + Domain), schick Fehlermeldungen zurück, wenn etwas scheitert, und teile Secrets (Passwörter, API-Keys) nicht in Chats, denen du nicht vertraust. Die Schritte unten bleiben die Quelle der Wahrheit; der Agent führt dich nur durch.

Voraussetzungen

  • Node.js 20+
  • PostgreSQL 14+ (oder das mitgelieferte Docker Compose)
  • Git
  • Docker & Docker Compose (für produktionsnahe Setups stark empfohlen)

Optional, aber nützlich:

  • Domain + Reverse-Proxy (Caddy, Nginx, Traefik) für HTTPS
  • SMTP für Magic-Link-Login (und Einladungs-E-Mails)
  • Google- und/oder Microsoft-Entra-ID-OAuth-Apps für Mitarbeiter-Login
  • LLM-API-Key (OpenAI, Anthropic, xAI usw.)

Schnellstart (empfohlen – Docker Compose)

  1. Klonen und Verzeichnis öffnen:
git clone https://github.com/felixkrusch/entrytwo.git
cd entrytwo/entrytwo_v1
  1. Beispiel-Umgebung kopieren:
cp .env.example .env
  1. .env bearbeiten und mindestens setzen:
  • DATABASE_URL (oder Compose-Defaults nutzen)
  • POSTGRES_PASSWORD (von Compose benötigt)
  • AUTH_SECRET – erzeugen mit: openssl rand -base64 48 (≥ 32 Zeichen)
  • ENCRYPTION_KEY – erzeugen mit: openssl rand -hex 32 (64 Hex-Zeichen; Bank-Feeds / Secrets)
  • JOB_RUNNER_SECRET – erzeugen mit: openssl rand -base64 48
  • UPDATER_TOKEN – erzeugen mit: openssl rand -base64 48 (für den Updater-Sidecar)
  • Mindestens einen LLM-Key, wenn du KI/Chat willst (OPENAI_API_KEY, ANTHROPIC_API_KEY usw.)
  • NEXT_LLM_PROVIDER und NEXT_LLM_MODEL (Defaults reichen meist für die Entwicklung)
  1. Stack starten:
docker compose up -d

Das startet:

  • app (Next.js auf Port 3000)
  • db (PostgreSQL)
  • worker (Hintergrundjobs)
  • updater (isolierter Sidecar für signierte Updates – siehe Self-Hosted Updates)
  • redis
  1. Migrationen und Seed:
docker compose exec app npx prisma migrate deploy
docker compose exec app npm run db:seed

(Lokale Entwicklung ohne Docker kann npx prisma migrate dev statt deploy nutzen.)

  1. http://localhost:3000 öffnen

Beim ersten Besuch ohne Admin-Benutzer kannst du das initiale ADMIN-Konto anlegen.

Umgebungsvariablen (die wichtigsten)

.env.example kopieren und ausfüllen:

Erforderlich (lokal oder Produktion)

  • DATABASE_URL
  • AUTH_SECRET (≥ 32 Zeichen)
  • POSTGRES_PASSWORD (bei Compose)

In Produktion erforderlich (App startet nicht sauber / Health bleibt degraded ohne diese)

  • ENCRYPTION_KEY (64 Hex-Zeichen)
  • JOB_RUNNER_SECRET
  • AUTH_URL (öffentliche Origin, z. B. https://books.example.com)
  • AUTH_TRUST_HOST=true (hinter nginx/caddy/traefik)
  • Mindestens eine echte Anmeldemethode:
    • SMTP: SMTP_HOST, SMTP_USER, SMTP_PASS (idealerweise SMTP_FROM), und/oder
    • Google: GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET, und/oder
    • Microsoft: MICROSOFT_ENTRA_ID_ID + MICROSOFT_ENTRA_ID_SECRET (+ Issuer)

Stark empfohlen

  • UPDATER_TOKEN – Shared Secret für den Updater-Sidecar
  • LLM-Key + NEXT_LLM_PROVIDER / NEXT_LLM_MODEL

Für Produktion / Updates

  • UPDATE_MANIFEST_URL – zeigt auf dein signiertes Release-Manifest
  • Cosign-Einstellungen (COSIGN_IDENTITY, COSIGN_PUBLIC_KEY usw.)
  • STRIPE_WEBHOOK_SECRET / PayPal-Secrets (bei Processor-Feeds)

Vollständige Liste in der App-.env.example. Auth-Go-Live: App-Repo docs/VPS-Auth-Install.md.

Manuelles Postgres (ohne Docker)

  1. Datenbank anlegen:
CREATE DATABASE entrytwo;
CREATE USER entrytwo WITH PASSWORD 'entrytwo_dev_password';
GRANT ALL PRIVILEGES ON DATABASE entrytwo TO entrytwo;
  1. In .env setzen:
DATABASE_URL="postgresql://entrytwo:entrytwo_dev_password@localhost:5432/entrytwo"
  1. Deps installieren, migrieren, seeden:
npm install
npx prisma migrate dev
npm run db:seed
npm run dev

Erster Admin (Bootstrap)

entrytwo ist so gebaut, dass der allererste Benutzer einer frischen Installation ADMIN wird.

  • Existiert kein ADMIN, erlaubt der Anmelde-/Onboarding-Flow die Erstellung (Firma, Sprache, Standard-Kontenplan).
  • Danach kommen weitere Benutzer nur per Einladung (Admin → Benutzer). Anmeldung mit genau der eingeladenen E-Mail über Google, Microsoft oder Magic Link.
  • Rollen: ADMIN, ACCOUNTANT oder VIEWER.
  • In Produktion muss ADMIN TOTP (2FA) einrichten, bevor die App nutzbar ist.

Siehe Erste Schritte.

Authentifizierung (Kurzüberblick)

UmgebungAnmeldung
Lokale EntwicklungSofort-E-Mail („Weiter“) – kein SMTP nötig
ProduktionMagic Link (SMTP) und/oder Google-OAuth und/oder Microsoft Entra ID

Sofort-E-Mail ist bei NODE_ENV=production deaktiviert. OAuth-Redirect-URIs: {AUTH_URL}/api/auth/callback/google und .../microsoft-entra-id.

Health und grundlegende Prüfung

  • App-Health: GET /api/health
  • Produktion sollte "ready": true und auth.productionReady: true melden
  • Nach docker compose up -d hat der App-Container einen Healthcheck auf diesem Endpoint

Produktion / VPS (kurz)

Vor dem ersten produktiven Start:

  1. Secrets — AUTH_SECRET, ENCRYPTION_KEY, JOB_RUNNER_SECRET, POSTGRES_PASSWORD (pro Installation neu).
  2. Anmeldung — volles SMTP (SMTP_HOST + USER + PASS) und/oder Google/Microsoft-OAuth. Sofort-E-Mail ist in Produktion aus.
  3. Öffentliche URL — AUTH_URL=https://deine.domain, AUTH_TRUST_HOST=true.
  4. DNS — A-Record auf die VPS-IP bevor HTTPS erwartet wird. Nach spät gesetztem DNS Reverse-Proxy neu starten (z. B. Caddy).
  5. Deploy — docker compose up -d --build (Entrypoint führt Migrationen aus). /api/health → ready: true.
  6. Erster Admin — Bootstrap, danach TOTP für ADMIN.

RAM: ≥ 2 GB für einen Stack; ~4 GB, wenn mehrere Installationen auf einem Host laufen.

Details: App-Repo docs/PRODUCTION.md und docs/VPS-Auth-Install.md.

Typische nächste Schritte

  • Erste Schritte lesen
  • Mindestens einen LLM-Key setzen und den Chat testen
  • SMTP und/oder OAuth konfigurieren, damit Teammitglieder sich anmelden können
  • (Produktion) HTTPS, starke Secrets und die VPS-Auth-Checkliste im App-Repo
  • (Später) Bank-Feeds, Updates und Lizenzierung

Siehe auch: