From 3abe5d2b85224fab56ff9b58698ed0480268b1a2 Mon Sep 17 00:00:00 2001 From: z3n Date: Fri, 22 May 2026 14:10:47 +0000 Subject: [PATCH] docs: ajout guide et script d'installation locale sans Docker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - documentation/local-setup.md : guide complet (prérequis, install manuelle, démarrage, config, vérification) - scripts/setup-local.sh : script automatisé (check prérequis, création DB PostgreSQL, install CLIs et dépendances) Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude Co-Authored-By: Happy --- documentation/local-setup.md | 145 ++++++++++++++++++++++++++++++ scripts/setup-local.sh | 169 +++++++++++++++++++++++++++++++++++ 2 files changed, 314 insertions(+) create mode 100644 documentation/local-setup.md create mode 100755 scripts/setup-local.sh diff --git a/documentation/local-setup.md b/documentation/local-setup.md new file mode 100644 index 0000000..8c5387e --- /dev/null +++ b/documentation/local-setup.md @@ -0,0 +1,145 @@ +# 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 +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 + +```bash +# 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 + +```bash +npm install -g @asyncapi/cli@6.0.0 +npm install -g @redocly/cli +``` + +### 3. Dépendances Node.js + +```bash +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** +```bash +cd back +pnpm run start:dev +# API disponible sur http://localhost:3000 +# Health check : http://localhost:3000/health +``` + +**Terminal 2 — Frontend** +```bash +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` : + +```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 | + +--- + +## 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. diff --git a/scripts/setup-local.sh b/scripts/setup-local.sh new file mode 100755 index 0000000..2052bac --- /dev/null +++ b/scripts/setup-local.sh @@ -0,0 +1,169 @@ +#!/usr/bin/env bash +# ============================================================================= +# Datacat — Script d'installation locale (sans Docker) +# Usage : bash scripts/setup-local.sh +# ============================================================================= + +set -e + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +ok() { echo -e "${GREEN}✔${NC} $1"; } +warn() { echo -e "${YELLOW}⚠${NC} $1"; } +err() { echo -e "${RED}✖${NC} $1"; exit 1; } +info() { echo -e "${BLUE}→${NC} $1"; } + +echo "" +echo "======================================" +echo " Datacat — Setup local (sans Docker)" +echo "======================================" +echo "" + +# ----------------------------------------------------------------------------- +# 1. Vérification des prérequis +# ----------------------------------------------------------------------------- +info "Vérification des prérequis..." + +# Node.js +if ! command -v node &>/dev/null; then + err "Node.js non trouvé. Installer Node.js 22 LTS : https://nodejs.org" +fi +NODE_VERSION=$(node -v) +ok "Node.js $NODE_VERSION" + +# pnpm +if ! command -v pnpm &>/dev/null; then + warn "pnpm non trouvé. Installation..." + npm install -g pnpm@10.33.0 +fi +PNPM_VERSION=$(pnpm -v) +ok "pnpm $PNPM_VERSION" + +# PostgreSQL +if ! command -v psql &>/dev/null; then + err "PostgreSQL non trouvé. Installer PostgreSQL 17 : https://www.postgresql.org/download/" +fi +PG_VERSION=$(psql --version) +ok "$PG_VERSION" + +# git (requis par asyncapi CLI) +if ! command -v git &>/dev/null; then + err "git non trouvé. Installer git : https://git-scm.com" +fi +ok "git $(git --version | awk '{print $3}')" + +echo "" + +# ----------------------------------------------------------------------------- +# 2. Base de données PostgreSQL +# ----------------------------------------------------------------------------- +info "Configuration de la base de données..." + +DB_NAME="datacat" +DB_USER="datacat" +DB_PASS="datacat" + +# Détecter l'utilisateur postgres +PG_CMD="" +if sudo -u postgres psql -c '\q' &>/dev/null 2>&1; then + PG_CMD="sudo -u postgres psql" +elif psql -U postgres -c '\q' &>/dev/null 2>&1; then + PG_CMD="psql -U postgres" +else + warn "Impossible de se connecter à PostgreSQL automatiquement." + warn "Exécutez manuellement les commandes suivantes :" + echo "" + echo " CREATE DATABASE $DB_NAME;" + echo " CREATE USER $DB_USER WITH PASSWORD '$DB_PASS';" + echo " GRANT ALL PRIVILEGES ON DATABASE $DB_NAME TO $DB_USER;" + echo " ALTER DATABASE $DB_NAME OWNER TO $DB_USER;" + echo "" + read -p "Appuyez sur Entrée une fois la base créée..." +fi + +if [ -n "$PG_CMD" ]; then + # Créer l'utilisateur s'il n'existe pas + if $PG_CMD -tc "SELECT 1 FROM pg_roles WHERE rolname='$DB_USER'" | grep -q 1; then + ok "Utilisateur '$DB_USER' déjà existant" + else + $PG_CMD -c "CREATE USER $DB_USER WITH PASSWORD '$DB_PASS';" &>/dev/null + ok "Utilisateur '$DB_USER' créé" + fi + + # Créer la base si elle n'existe pas + if $PG_CMD -tc "SELECT 1 FROM pg_database WHERE datname='$DB_NAME'" | grep -q 1; then + ok "Base de données '$DB_NAME' déjà existante" + else + $PG_CMD -c "CREATE DATABASE $DB_NAME;" &>/dev/null + $PG_CMD -c "GRANT ALL PRIVILEGES ON DATABASE $DB_NAME TO $DB_USER;" &>/dev/null + $PG_CMD -c "ALTER DATABASE $DB_NAME OWNER TO $DB_USER;" &>/dev/null + ok "Base de données '$DB_NAME' créée" + fi +fi + +echo "" + +# ----------------------------------------------------------------------------- +# 3. CLIs de génération de documentation +# ----------------------------------------------------------------------------- +info "Installation des CLIs de génération..." + +if command -v asyncapi &>/dev/null; then + ok "asyncapi CLI déjà installé ($(asyncapi --version 2>/dev/null || echo 'version inconnue'))" +else + info "Installation de @asyncapi/cli@6.0.0..." + npm install -g @asyncapi/cli@6.0.0 + ok "asyncapi CLI installé" +fi + +if command -v redocly &>/dev/null; then + ok "redocly CLI déjà installé" +else + info "Installation de @redocly/cli..." + npm install -g @redocly/cli + ok "redocly CLI installé" +fi + +echo "" + +# ----------------------------------------------------------------------------- +# 4. Installation des dépendances Node.js +# ----------------------------------------------------------------------------- +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +ROOT_DIR="$(dirname "$SCRIPT_DIR")" + +info "Installation des dépendances (shared)..." +cd "$ROOT_DIR/shared" && pnpm install --silent +ok "shared" + +info "Installation des dépendances (back)..." +cd "$ROOT_DIR/back" && pnpm install --silent +ok "back" + +info "Installation des dépendances (front-public)..." +cd "$ROOT_DIR/front-public" && pnpm install --silent +ok "front-public" + +echo "" + +# ----------------------------------------------------------------------------- +# 5. Résumé +# ----------------------------------------------------------------------------- +echo "======================================" +echo -e "${GREEN} Installation terminée !${NC}" +echo "======================================" +echo "" +echo "Pour démarrer l'application :" +echo "" +echo " Terminal 1 — Backend :" +echo " cd back && pnpm run start:dev" +echo " → API sur http://localhost:3000" +echo "" +echo " Terminal 2 — Frontend :" +echo " cd front-public && pnpm run start" +echo " → App sur http://localhost:4200" +echo ""