docs: ajout guide et script d'installation locale sans Docker
- 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 <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
145
documentation/local-setup.md
Normal file
145
documentation/local-setup.md
Normal file
@@ -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.
|
||||||
169
scripts/setup-local.sh
Executable file
169
scripts/setup-local.sh
Executable file
@@ -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 ""
|
||||||
Reference in New Issue
Block a user