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