datacat/documentation/local-setup.md

Lancer Datacat en local (sans Docker)

Prérequis

Outil	Version	Lien
Node.js	22 LTS	https://nodejs.org
pnpm	10.33.0	npm install -g pnpm@10.33.0
PostgreSQL	17	https://www.postgresql.org/download/
git	toute version récente	https://git-scm.com

git est requis par le CLI AsyncAPI pour installer ses templates.

---

Installation rapide (script)

bash scripts/setup-local.sh

Le script :

1. Vérifie les prérequis
2. Crée la base PostgreSQL datacat
3. Installe @asyncapi/cli et @redocly/cli globalement
4. Installe les dépendances npm des trois packages

---

Installation manuelle

1. Base de données PostgreSQL

# Linux
sudo -u postgres psql << 'SQL'
CREATE DATABASE datacat;
CREATE USER datacat WITH PASSWORD 'datacat';
GRANT ALL PRIVILEGES ON DATABASE datacat TO datacat;
ALTER DATABASE datacat OWNER TO datacat;
SQL

# macOS (Homebrew)
psql postgres << 'SQL'
CREATE DATABASE datacat;
CREATE USER datacat WITH PASSWORD 'datacat';
GRANT ALL PRIVILEGES ON DATABASE datacat TO datacat;
ALTER DATABASE datacat OWNER TO datacat;
SQL

# Windows (PowerShell — depuis le dossier bin de PostgreSQL)
psql -U postgres -c "CREATE DATABASE datacat;"
psql -U postgres -c "CREATE USER datacat WITH PASSWORD 'datacat';"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE datacat TO datacat;"
psql -U postgres -c "ALTER DATABASE datacat OWNER TO datacat;"

2. CLIs de génération de docs

npm install -g @asyncapi/cli@6.0.0
npm install -g @redocly/cli

3. Dépendances Node.js

cd shared       && pnpm install
cd ../back      && pnpm install
cd ../front-public && pnpm install

---

Démarrage

Ouvrir deux terminaux depuis la racine du projet :

Terminal 1 — Backend

cd back
pnpm run start:dev
# API disponible sur http://localhost:3000
# Health check : http://localhost:3000/health

Terminal 2 — Frontend

cd front-public
pnpm run start
# Application disponible sur http://localhost:4200

---

Configuration

Les variables d'environnement ont des valeurs par défaut. Aucun fichier .env n'est nécessaire si la base PostgreSQL est créée avec les identifiants par défaut (datacat/datacat).

Pour surcharger, créer back/.env :

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=datacat
DATABASE_USER=datacat
DATABASE_PASSWORD=datacat

# Répertoire de sortie des docs générées
DOCS_OUTPUT_DIR=./docs-output

# Port du backend (défaut : 3000)
PORT=3000

---

Vérification

URL	Attendu
http://localhost:3000/health	{"status":"ok"}
http://localhost:3000/api/apis	{"items":[], "total":0, ...}
http://localhost:4200	Page d'accueil Datacat
http://localhost:4200/browse	Arborescence des dossiers
http://localhost:4200/upload	Formulaire d'import YAML

---

Fichiers YAML de test

Des exemples sont disponibles dans documentation/ :

Fichier	Type	Description
files-samples-oas/petstore.yaml	OpenAPI 3.0	CRUD animaux
files-samples-asyncapi/user-events.yaml	AsyncAPI 3.0	Événements utilisateurs

---

Fixtures & re-seed

Les données de démo (catégories + APIs) sont définies dans back/src/modules/seeder/seeder.service.ts.

Structure des fixtures

E-commerce          (racine)
  └─ Produits
  └─ Commandes
  └─ Notifications
Infrastructure      (racine)
  └─ Événements
Identité & Accès    (racine)
  └─ Authentification

5 APIs de démo y sont rattachées (Petstore, Streetlights Kafka, Account Service, Orders, Auth JWT).

Modifier les fixtures

Éditer directement back/src/modules/seeder/seeder.service.ts :

• Catégories : bloc categoryRepo.save(categoryRepo.create({...})) dans la méthode seed(). Utiliser parentId: null pour une racine, ou parentId: autreCategorie.id pour un enfant.
• APIs : tableau passé à apiRepo.save([...]). Chaque entrée référence une catégorie via categoryId.
• YAML : les constantes en haut du fichier (PETSTORE_YAML, ORDERS_YAML, etc.) contiennent le YAML inliné de chaque API.

Régénérer la base de données

Le seeder est idempotent : il ne s'exécute pas si la table api_entries contient déjà des lignes.

Pour forcer un re-seed complet (vide tout et recrée), utiliser la variable FORCE_RESEED=true :

Avec Docker :

docker compose -f infra/docker-compose.yml stop backend
docker compose -f infra/docker-compose.yml run --rm -e FORCE_RESEED=true backend

Sans Docker (local) :

cd back
FORCE_RESEED=true pnpm run start:dev

Ou via back/.env :

FORCE_RESEED=true

Penser à retirer FORCE_RESEED=true du .env après le redémarrage, sinon la base sera réinitialisée à chaque démarrage.

Le seeder supprime toutes les entrées api_entries et categories, nettoie le répertoire docs-output, puis recrée tout depuis seed(). Les logs confirment l'opération :

[Seeder] Reset complet — données supprimées, docs nettoyées.
[Seeder] 8 catégories et 5 APIs de démo créées — génération docs en cours...

---

Notes

• Schéma DB : TypeORM crée et synchronise automatiquement les tables au démarrage (mode synchronize: true hors production). Aucune migration manuelle nécessaire.
• Génération de docs : asynchrone — après l'upload, le statut passe de PENDING à GENERATED une fois le CLI terminé.
• Proxy Angular : le fichier front-public/proxy.conf.json redirige /api vers http://localhost:3000. Ne pas modifier.