senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/docs/MONOREPO_ORCHESTRATION.md
senke b1ed46b142 small fixes : cors + login loop
2026-02-07 20:36:48 +01:00

5.8 KiB
Raw Blame History

Orchestration et gestion du monorepo Veza

Ce document décrit la structure du Makefile modulaire et recommande des outils open source pour orchestrer le projet pendant son développement.

1. Structure actuelle du Makefile

Organisation

Fichier Rôle
Makefile Point d’entrée unique ; inclut les fragments et définit le goal par défaut (help)
make/config.mk Source de vérité : services, ports, chemins (SERVICE_DIR_, PORT_, COMPOSE_*, ROOT, etc.)
make/ui.mk Couleurs et ECHO_CMD
make/help.mk Cible help et dashboard
make/tools.mk check-tools, install-tools, install-deps, check-ports
make/infra.mk infra-up, infra-down, db-migrate, db-shell, redis-shell
make/dev.mk dev, dev-backend, dev-web, dev-<service>, stop-local-services
make/build.mk build-*, build-all, build-all-native, build-service
make/test.mk test, test-<service>, lint, lint-<service>, fmt, status
make/services.mk start-service, stop-service, restart-service, logs-service (Docker)
make/high.mk setup, stop-all, clean, deploy-docker, deploy-incus, status-full, web-minimal
make/incus.mk Toutes les cibles Incus (network, deploy, start, stop, status, logs)

Personnalisation

  • Ajouter un service : dans make/config.mk, ajouter le nom dans SERVICES, puis définir SERVICE_DIR_<nom> et PORT_<nom> si besoin. Adapter les règles dans les .mk qui font du case-by-service (ex. dev.mk, build.mk).
  • Changer un port : dans make/config.mk ou via .env (ex. PORT_web=3000).
  • Changer un chemin : modifier SERVICE_DIR_<service> dans make/config.mk.
  • Override global : utiliser .env (chargé par config.mk avec -include .env).

Cibles par service

  • make dev-web, make dev-backend-api, make dev-chat-server, make dev-stream-server
  • make test-web, make test-backend-api, …
  • make lint-web, make lint-backend-api, …
  • make build-service SERVICE=backend-api

2. Outils open source recommandés

En complément (ou en partie en remplacement) du Makefile, ces outils peuvent aider à orchestrer le monorepo.

2.1 Turborepo (JS/TS)

  • Site : turbo.build
  • Rôle : Cache des tâches et pipeline de build/test/lint pour les workspaces npm.
  • Atouts : Cache distant optionnel, parallélisation, turbo run build --filter=./apps/web, intégration CI simple.
  • Limites : Ciblé npm/pnpm workspaces (apps/web, packages/design-system). Les backends Go/Rust restent gérés par le Makefile ou des scripts.
  • Usage typique : turbo run build, turbo run test --filter=web, turbo run lint.

À envisager si tu veux un cache et un graphe de tâches fiable pour la partie Node/TS, tout en gardant Make pour l’infra et les backends.

2.2 Nx

  • Site : nx.dev
  • Rôle : Monorepo “full stack” : graphe de dépendances, cache, affected (build/test uniquement sur ce qui a changé), plugins (React, Node, Go, etc.).
  • Atouts : Très flexible, “affected” puissant, support multi-langage (y compris Go via plugins ou custom targets).
  • Limites : Plus lourd à configurer et à maintenir que Turborepo ; courbe d’apprentissage plus forte.

Utile si le monorepo grossit encore et que tu veux “affected”, cache partagé et une seule interface pour build/test/lint (y compris backends).

2.3 Just (command runner)

  • Site : github.com/casey/just
  • Rôle : Remplacer une partie des cibles Make par un fichier justfile (syntaxe plus lisible, arguments nommés, pas de tabs).
  • Atouts : Scripts lisibles, facile à partager entre devs, multiplateforme (Windows possible).
  • Limites : Pas de vrai “graphe de tâches” ni cache ; plutôt un complément ou un remplacement léger du Make pour les commandes métier.

Exemple : just dev, just test web, just deploy docker.

2.4 Mise (ex-asdf)

  • Site : mise.jdx.dev
  • Rôle : Gestion des versions des runtimes (Node, Go, Rust, Python) au niveau du repo ou de la machine.
  • Atouts : Un seul outil pour .node-version, .go-version, etc. ; reproductibilité des envs entre dev et CI.
  • Limites : Ne remplace pas le Makefile ; il assure seulement que les bonnes versions sont actives.

Recommandé pour figer Node/Go/Rust et éviter les “ça marche chez moi”.

2.5 Tâche (Task)

  • Site : taskfile.dev
  • Rôle : Alternative au Make en YAML, avec variables, includes, dépendances entre tâches.
  • Atouts : Syntaxe YAML, parallélisation, bon pour des pipelines déclaratifs.
  • Limites : Un outil de plus ; si le Make modulaire te convient, pas obligatoire.

3. Synthèse

Besoin Outil suggéré
Un seul endroit pour config (ports, services, chemins) make/config.mk (déjà en place)
Cache + pipeline pour JS/TS uniquement Turborepo
Affected + cache + multi-langage (y compris Go/Rust) Nx
Commandes lisibles, peu de dépendance à Make Just
Versions Node/Go/Rust reproductibles Mise
Tout garder en Make mais mieux structuré Makefile + make/*.mk (actuel)

Recommandation pragmatique : garder le Makefile modulaire comme entrée principale (infra, dev, deploy, Incus). Si la partie frontend/npm devient la plus coûteuse (builds, tests, lint), ajouter Turborepo pour les workspaces npm et appeler turbo depuis le Makefile si besoin (ex. make test → infra-up + turbo run test + tests Go/Rust). Pour les versions des runtimes, Mise (ou asdf) dans le repo et en CI améliore la reproductibilité sans toucher au reste.