Goooy Ontwikkelaarsgids

De technische fundamenten voor de mensen die Goooy bouwen, uitrollen en integreren: waaruit het systeem bestaat, hoe u het uitrolt en hoe het wordt geconfigureerd.

Goooy is een complete groupware-suite die u zelf host: e-mail, agenda, contacten, taken, notities, chat, bestanden, videovergaderingen, gezamenlijke office en een adminconsole, allemaal vanuit één applicatie, één datamodel en één Helm-chart. U bent eigenaar van de servers, de data en de sleutels.

Deze gids behandelt het platform zelf. Het dagelijkse beheer (de adminconsole, organisaties & gebruikers, authenticatiebeleid, de mailserver, apparaatbeheer, migratie, multi-tenancy en back-ups) staat in de Beheerdersgids; het gebruikersperspectief op de apps staat in de Gebruikersgids. Voor diepgaande technische details heeft de map docs/ in de productbroncode aparte referenties (architectuur, beveiliging, mailserver, tenancy, deployment, migratie en de native-clientprotocollen).

Inhoud

• Wat u draait
• Goooy uitrollen
• Essentiële configuratie

Wat u draait

Goooy is een modulair monoliet: één Fastify/TypeScript-API ondersteund door PostgreSQL, Redis en S3-compatibele objectopslag, plus een React-single-page-webapp die door nginx wordt geserveerd. Native clients (Outlook, Thunderbird, Apple Mail, telefoons) maken verbinding via de standaardprotocollen. Optioneel maakt een echte mailserver (Postfix + Dovecot + Rspamd) van de API de delivery hub voor inkomende en uitgaande internetmail.

   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)  │
                       └──────────┘  └────────┘  └──────────┘

Ondersteunende services en wat ze bevatten:

De hele suite wordt geleverd als een Helm-chart (deploy/helm/goooy) die Postgres/Redis/MinIO voor u kan meeleveren of kan verwijzen naar beheerde externe instanties.

Goooy uitrollen

Kubernetes (aanbevolen)

Een minimale installatie brengt de volledige suite omhoog: api- + web-Deployments, meegeleverde PostgreSQL/Redis/MinIO, en een Ingress die de app en elk native-clientprotocolpad path-routet:

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

De Ingress routeert / naar de webapp en /api, /ws, /dav, /share, /autodiscover, /.well-known/autoconfig, /mail/config en /Microsoft-Server-ActiveSync naar de API. TLS termineert hier.

Meegeleverde versus externe ondersteunende services. Elke store kan worden meegeleverd (de standaard) of extern zijn:

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=…

Productieharding. Zet autoscaling, disruption budgets, nachtelijke back-ups, automatische TLS en uw eigen secret aan:

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

Elke instelling is gedocumenteerd in deploy/helm/goooy/values.yaml; de volledige topologie staat in Deployment.

Lokaal evalueren (Docker Compose)

Om Goooy op een laptop te proberen:

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

Open http://localhost:5173 en meld u aan als de bootstrap-admin. Twee demogebruikers (alice@goooy.local / bob@goooy.local, wachtwoord demo) laten u mail tussen accounts versturen en de lokale bezorging aan het werk zien.

Container-images

Multi-stage builds, allemaal draaiend als non-root (uid 1000) onder een restrictieve pod security context:

• api: Node 22, draait prisma migrate deploy en daarna de server; stelt HTTP (4000) en de SMTP/LMTP-ingestpoorten (2525/2526) beschikbaar.
• web: Vite-build geserveerd door nginx; reverse-proxyt /api, /ws en de protocolpaden, stelt beveiligingsheaders in en doet SPA-fallback.
• marketing: een statische publieke Astro-site (optioneel; zie de Beheerdersgids).
• mail: Postfix, Dovecot, Rspamd (alleen wanneer de mailserver is ingeschakeld).

Essentiële configuratie

Configuratie is gecentraliseerd en Zod-gevalideerd bij het opstarten. De API faalt direct als JWT_SECRET (≥16 tekens) of DATABASE_URL ontbreekt of ongeldig is, zodat een verkeerd geconfigureerde deployment nooit in een half-kapotte toestand start. Al het andere heeft verstandige standaardwaarden.

De belangrijkste variabelen:

Secrets. JWT_SECRET en DATABASE_URL horen uit een Kubernetes Secret te komen die u aanlevert (secret.existingSecret). Zet nooit de chart-standaard in productie. JWT_SECRET doet dubbel werk: het verzegelt ook S/MIME-privésleutels, SSO-clientsecrets en migratiecredentials in rust, dus het wijzigen ervan maakt die verzegelde waarden ongeldig. Roteer weloverwogen. De volledige env-tabel staat in Deployment.

Waar nu naartoe

• De Beheerdersgids behandelt het draaien van de uitgerolde suite: de adminconsole, organisaties & gebruikers, authenticatiebeleid, de mailserver, apparaatbeheer, migratie, multi-tenancy en back-ups.
• De Gebruikersgids is het gebruikersperspectief op elke app.
• De volledige technische referentie (architectuur, datamodel, mailserver, tenancy, deployment, migratie en de native-clientprotocollen) wordt geleverd met de productbroncode.