Guide du développeur Goooy

Les fondations techniques pour les personnes qui construisent, déploient et intègrent Goooy : de quoi le système est fait, comment le déployer et comment il est configuré.

Goooy est une suite de groupware complète que vous hébergez vous-même : courrier, calendrier, contacts, tâches, notes, conversation, fichiers, réunions vidéo, office collaboratif et une console d’administration, le tout depuis une seule application, un seul modèle de données et un seul chart Helm. Vous possédez les serveurs, les données et les clés.

Ce guide couvre la plateforme elle-même. L’exploitation au quotidien (la console d’administration, les organisations et utilisateurs, la politique d’authentification, le serveur de messagerie, la gestion des appareils, la migration, la multi-tenancy et les sauvegardes) fait l’objet du Guide de l’administrateur ; la vue des applications côté utilisateur final est le Guide de l’utilisateur. Pour les détails techniques approfondis, le dossier docs/ du code source du produit contient des références dédiées (architecture, sécurité, serveur de messagerie, multi-tenancy, déploiement, migration et les protocoles clients natifs).

Sommaire

• Ce que vous exécutez
• Déployer Goooy
• L’essentiel de la configuration

Ce que vous exécutez

Courrier, calendriers, contacts et fichiers proposent notamment IMAP, SMTP, CalDAV, CardDAV et WebDAV. Chaque version de client et politique de compte doit être testée. L’interopérabilité réelle avec Outlook, Outlook mobile et l’équivalence Exchange ne sont pas établies.

Goooy est un monolithe modulaire : une seule API Fastify/TypeScript adossée à PostgreSQL, Redis et un stockage objet compatible S3, plus une application web monopage React servie par nginx. Les clients natifs (Outlook, Thunderbird, Apple Mail, téléphones) se connectent via les protocoles standard. En option, un vrai serveur de messagerie (Postfix + Dovecot + Rspamd) transforme l’API en centre de distribution du courrier Internet entrant et sortant.

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

Les services sous-jacents et ce qu’ils contiennent :

Toute la suite est livrée sous forme de chart Helm (deploy/helm/goooy) qui peut inclure Postgres/Redis/Garage pour vous ou pointer vers des instances externes managées.

Déployer Goooy

Kubernetes (recommandé)

Une installation minimale met en route toute la suite : les Deployments api + web, PostgreSQL/Redis/Garage inclus, et un Ingress qui route par chemin l’application et chaque chemin de protocole client natif :

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

L’Ingress route / vers l’application web et /api, /ws, /dav, /share, /autodiscover, /.well-known/autoconfig, /mail/config et /Microsoft-Server-ActiveSync vers l’API. Le TLS se termine ici.

Services sous-jacents inclus ou externes. Chaque store peut être inclus (par défaut) ou externe :

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

Durcissement pour la production. Activez l’autoscaling, les budgets de disruption, les sauvegardes nocturnes, le TLS automatique et votre propre secret :

# --reuse-values keeps what you set at install time; without it helm resets every other value to the chart default.
# autoscaling.enabled: HPA for api + web (needs metrics-server)
# backup.enabled: nightly pg_dump CronJob
helm upgrade goooy ./deploy/helm/goooy --reuse-values \
  --set autoscaling.enabled=true \
  --set podDisruptionBudget.enabled=true \
  --set backup.enabled=true \
  --set ingress.tls.clusterIssuer=letsencrypt-prod \
  --set secret.existingSecret=goooy-prod-secret

Chaque paramètre est documenté dans deploy/helm/goooy/values.yaml ; la topologie complète figure dans Déploiement.

Évaluation locale (Docker Compose)

Pour essayer Goooy sur un ordinateur portable :

cp .env.example .env                                  # sets JWT_SECRET, DATABASE_URL, …
docker compose up -d postgres redis garage 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

Ouvrez http://localhost:5173 et connectez-vous en tant qu’administrateur de bootstrap. Deux utilisateurs de démonstration (alice@goooy.local / bob@goooy.local, mot de passe demo) vous permettent d’envoyer du courrier entre les comptes et d’observer la distribution locale fonctionner.

Images de conteneurs

Des builds multi-étapes, tous exécutés en non-root (uid 1000) sous un contexte de sécurité de pod restrictif :

• api : Node 26, exécute prisma migrate deploy puis le serveur ; expose HTTP (4000) et les ports d’ingestion SMTP/LMTP (2525/2526).
• web : build Vite servi par nginx ; relaie en proxy inverse /api, /ws et les chemins de protocole, définit les en-têtes de sécurité et effectue le repli SPA.
• marketing : un site public statique Astro (optionnel ; voir le Guide de l’administrateur).
• mail : Postfix, Dovecot, Rspamd (uniquement lorsque le serveur de messagerie est activé).

L’essentiel de la configuration

La configuration est centralisée et validée par Zod au démarrage. L’API échoue rapidement si JWT_SECRET (≥16 caractères) ou DATABASE_URL est manquant ou invalide, pour qu’un déploiement mal configuré ne démarre jamais dans un état à moitié cassé. Tout le reste a des valeurs par défaut raisonnables.

Les variables les plus importantes :

Secrets. JWT_SECRET et DATABASE_URL doivent provenir d’un Secret Kubernetes que vous fournissez (secret.existingSecret). N’expédiez jamais la valeur par défaut du chart en production. JWT_SECRET a un double rôle : il scelle aussi les clés privées S/MIME, les secrets clients SSO et les identifiants de migration au repos, donc le changer invalide ces valeurs scellées. Effectuez la rotation de façon délibérée. La table complète des variables d’environnement figure dans Déploiement.

Où aller ensuite

• Le Guide de l’administrateur couvre l’exploitation de la suite déployée : la console d’administration, les organisations et utilisateurs, la politique d’authentification, le serveur de messagerie, la gestion des appareils, la migration, la multi-tenancy et les sauvegardes.
• Le Guide de l’utilisateur est la vue de chaque application côté utilisateur final.
• La référence technique complète (architecture, modèle de données, serveur de messagerie, multi-tenancy, déploiement, migration et les protocoles clients natifs) est fournie avec le code source du produit.