Goooy Entwicklerhandbuch

Die technischen Grundlagen für die Personen, die Goooy bauen, bereitstellen und integrieren: woraus das System besteht, wie es bereitgestellt wird und wie es konfiguriert ist.

Goooy ist eine vollständige Groupware-Suite, die Sie selbst hosten: E-Mail, Kalender, Kontakte, Aufgaben, Notizen, Chat, Dateien, Videobesprechungen, kollaboratives Office und eine Admin-Konsole, alles aus einer Anwendung, einem Datenmodell und einem Helm-Chart. Ihnen gehören die Server, die Daten und die Schlüssel.

Dieses Handbuch behandelt die Plattform selbst. Der laufende Betrieb (die Admin-Konsole, Organisationen & Nutzer, Authentifizierungsrichtlinie, der Mailserver, Geräteverwaltung, Migration, Mandantenfähigkeit und Backups) steht im Administratorhandbuch; die Sicht der Endnutzer auf die Apps ist das Benutzerhandbuch. Für tiefe technische Details enthält der docs/-Ordner im Produktquellcode eigene Referenzen (Architektur, Sicherheit, Mailserver, Mandantenfähigkeit, Deployment, Migration und die nativen Client-Protokolle).

Inhalt

Was Sie betreiben
Goooy bereitstellen
Konfigurationsgrundlagen

Was Sie betreiben

Goooy ist ein modularer Monolith: eine einzelne Fastify/TypeScript-API, gestützt auf PostgreSQL, Redis und S3-kompatiblen Objektspeicher, sowie eine React-Single-Page-Web-App, die von nginx ausgeliefert wird. Native Clients (Outlook, Thunderbird, Apple Mail, Smartphones) verbinden sich über die Standardprotokolle. Optional macht ein echter Mailserver (Postfix + Dovecot + Rspamd) die API zum Zustellungs-Hub für ein- und ausgehende Internet-E-Mail.

   Browser ───────▶  web (React SPA, nginx)  ──proxies /api, /ws──▶
   Native clients ─▶  api (Fastify, modular monolith)
   (DAV · EAS ·                │         │          │
    Autodiscover ·     ┌───────▼──┐  ┌───▼────┐  ┌──▼───────┐
    IMAP/POP3/SMTP)    │PostgreSQL│  │ Redis  │  │ S3/MinIO │
                       │ (Prisma) │  │pub/sub │  │ (blobs)  │
                       └──────────┘  └────────┘  └──────────┘

Backing-Services und was sie enthalten:

Speicher	Rolle	Wenn er verloren geht
PostgreSQL	System of Record: alle strukturierten Daten und die Webmail-Ansicht der Nachrichten	Katastrophal; genau das sichern Sie
S3 / MinIO	Opake Blobs: Datei-Uploads (versioniert) und E-Mail-Anhänge	Datei-/Anhangsinhalte verloren
Redis	Nur flüchtig: Echtzeit-Pub/Sub, Präsenz, Besprechungsteilnehmerlisten	Echtzeit verschlechtert sich kurz; keine dauerhaften Daten verloren

Die gesamte Suite wird als Helm-Chart (deploy/helm/goooy) ausgeliefert, das Postgres/Redis/MinIO für Sie bündeln oder auf verwaltete externe Instanzen verweisen kann.

Goooy bereitstellen

Kubernetes (empfohlen)

Eine minimale Installation bringt die vollständige Suite zum Laufen: api- + web-Deployments, gebündeltes PostgreSQL/Redis/MinIO und ein Ingress, der die App und jeden nativen Client-Protokollpfad per Pfad-Routing verteilt:

helm install goooy ./deploy/helm/goooy \
  --namespace goooy --create-namespace \
  --set ingress.host=mail.example.com

Der Ingress leitet / an die Web-App und /api, /ws, /dav, /share, /autodiscover, /.well-known/autoconfig, /mail/config sowie /Microsoft-Server-ActiveSync an die API. TLS wird hier terminiert.

Gebündelte vs. externe Backing-Services. Jeder Speicher kann gebündelt (Standard) oder extern sein:

helm install goooy ./deploy/helm/goooy \
  --set postgresql.enabled=false --set externalDatabase.url=postgresql://… \
  --set redis.enabled=false      --set externalRedis.url=redis://… \
  --set minio.enabled=false      --set externalS3.endpoint=https://s3… \
  --set externalS3.accessKey=… --set externalS3.secretKey=…

Härtung für die Produktion. Aktivieren Sie Autoscaling, Disruption Budgets, nächtliche Backups, automatisches TLS und Ihr eigenes Secret:

helm upgrade goooy ./deploy/helm/goooy \
  --set autoscaling.enabled=true \            # HPA for api + web (needs metrics-server)
  --set podDisruptionBudget.enabled=true \
  --set backup.enabled=true \                 # nightly pg_dump CronJob
  --set ingress.tls.clusterIssuer=letsencrypt-prod \
  --set secret.existingSecret=goooy-prod-secret

Jede Stellschraube ist in deploy/helm/goooy/values.yaml dokumentiert; die vollständige Topologie steht in Deployment.

Lokale Evaluierung (Docker Compose)

Um Goooy auf einem Laptop auszuprobieren:

cp .env.example .env                                  # sets JWT_SECRET, DATABASE_URL, …
docker compose up -d postgres redis minio mailpit     # backing services
npm install
npm run db:migrate --workspace @goooy/api             # apply schema
npm run db:seed   --workspace @goooy/api              # bootstrap org + admin + demo users
npm run dev                                            # api :4000 + web :5173

Öffnen Sie http://localhost:5173 und melden Sie sich als Bootstrap-Admin an. Zwei Demo-Nutzer (alice@goooy.local / bob@goooy.local, Passwort demo) ermöglichen es Ihnen, E-Mails zwischen Konten zu senden und die lokale Zustellung in Aktion zu sehen.

Container-Images

Multi-Stage-Builds, alle laufen ohne Root-Rechte (uid 1000) unter einem restriktiven Pod-Security-Context:

api: Node 22, führt prisma migrate deploy und dann den Server aus; stellt HTTP (4000) und die SMTP/LMTP-Ingest-Ports (2525/2526) bereit.
web: Vite-Build, ausgeliefert von nginx; leitet /api, /ws und die Protokollpfade per Reverse-Proxy weiter, setzt Security-Header und erledigt den SPA-Fallback.
marketing: eine statische öffentliche Astro-Website (optional; siehe das Administratorhandbuch).
mail: Postfix, Dovecot, Rspamd (nur wenn der Mailserver aktiviert ist).

Konfigurationsgrundlagen

Die Konfiguration ist zentralisiert und beim Start Zod-validiert. Die API schlägt sofort fehl (fail-fast), wenn JWT_SECRET (≥16 Zeichen) oder DATABASE_URL fehlt oder ungültig ist, sodass eine fehlkonfigurierte Bereitstellung nie in einem halb kaputten Zustand startet. Alles Übrige hat sinnvolle Standardwerte.

Die wichtigsten Variablen:

Gruppe	Wichtige Variablen
Kern	`PUBLIC_WEB_URL`, `PUBLIC_API_URL`, `API_PORT` (4000)
Auth (erforderlich)	`JWT_SECRET` (≥16 Zeichen), `JWT_ACCESS_TTL` (900s), `JWT_REFRESH_TTL` (30d)
Daten (erforderlich)	`DATABASE_URL`, `REDIS_URL`
Objektspeicher	`S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY` / `S3_SECRET_KEY`
Mail (ausgehend)	`SMTP_HOST` / `SMTP_PORT` / `SMTP_SECURE`
Mail (eingehend)	`SMTP_INGEST_`, `LMTP_INGEST_`, `RSPAMD_URL`, `DOVECOT_LMTP_*`
Meet	`MEET_ICE_SERVERS` (STUN/TURN-Server als JSON)
Bootstrap	`BOOTSTRAP_ORG` / `BOOTSTRAP_DOMAIN` / `BOOTSTRAP_ADMIN_EMAIL` / `BOOTSTRAP_ADMIN_PASSWORD`

Secrets. JWT_SECRET und DATABASE_URL sollten aus einem von Ihnen bereitgestellten Kubernetes Secret stammen (secret.existingSecret). Bringen Sie niemals den Chart-Standardwert in die Produktion. JWT_SECRET erfüllt eine Doppelrolle: Es versiegelt außerdem S/MIME-Private-Keys, SSO-Client-Secrets und Migrationsanmeldedaten im Ruhezustand, sodass eine Änderung diese versiegelten Werte ungültig macht. Rotieren Sie bewusst. Die vollständige Env-Tabelle steht in Deployment.

Wie es weitergeht

Das Administratorhandbuch behandelt den Betrieb der bereitgestellten Suite: die Admin-Konsole, Organisationen & Nutzer, Authentifizierungsrichtlinie, den Mailserver, Geräteverwaltung, Migration, Mandantenfähigkeit und Backups.
Das Benutzerhandbuch ist die Endnutzersicht auf jede App.
Die vollständige technische Referenz (Architektur, Datenmodell, Mailserver, Mandantenfähigkeit, Deployment, Migration und die nativen Client-Protokolle) wird mit dem Produktquellcode ausgeliefert.