⚡ Démarrage

Trois chemins, du plus rapide au plus souple. Tous aboutissent au panneau d’administration, à l’API et au dictionnaire chargé : avec Docker sur http://localhost:3241 et http://localhost:3240, sans lui sur http://localhost:3000 et http://localhost:3010.

1. Lancer les images publiées

Aucun dépôt à cloner — un dossier, deux fichiers, Docker :

mkdir vocab-bloom-hub && cd vocab-bloom-hub
curl -fsSLO https://raw.githubusercontent.com/Fristail27/vocab-bloom-hub/main/docker-compose.yml
curl -fsSL  https://raw.githubusercontent.com/Fristail27/vocab-bloom-hub/main/.env.example -o .env

Ouvrez .env et définissez deux mots de passe : ADMIN_PASSWORD (la connexion administrateur) et POSTGRES_PASSWORD (la base de données incluse). Puis :

docker compose up -d

Le premier démarrage télécharge le dictionnaire et l’importe — quelques minutes. GET /api/ready répond 503 pendant ce temps et 200 ensuite ; connectez-vous alors avec ADMIN_USERNAME / ADMIN_PASSWORD du .env.

curl -s localhost:3240/api/ready            # {"status":"ok"}
curl -s localhost:3240/api/v1/words/run     # le dictionnaire répond

# recherche : les entrées correspondantes, la meilleure d'abord
curl -s 'localhost:3240/api/v1/search?search=run&limit=5'
# la même avec les sens, les exemples et les traductions
curl -s 'localhost:3240/api/v1/search/detailed?search=run&with_meanings=true'

2. Lancer depuis le dépôt

Le même fichier compose, construit depuis les sources — pour un fork ou une modification non publiée :

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
cp .env.example .env                           # les deux mêmes mots de passe
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

3. Lancer sans Docker

Un lancement de production sur la machine elle-même : Node.js 22.13+, Yarn 4 (corepack enable) et un Postgres accessible (docs/database.md).

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
yarn install
printf 'NODE_ENV=production\nDATABASE_URL=postgres://user:password@localhost:5432/vocab_bloom\nADMIN_USERNAME=admin\nADMIN_PASSWORD=change-me\nNEXT_PUBLIC_BASE_API_URL=http://localhost:3010/api\nDICTIONARY_AUTO_IMPORT=true\n' > .env
yarn build && yarn start                       # API :3010, administration :3000 ; le dictionnaire se charge seul au premier démarrage
yarn site:build && yarn start:site             # le site :3020, optionnel, dans un autre terminal

Derrière un domaine et TLS, avec systemd ou PM2 : docs/deployment/.

Pour le développement

Aucune base de données nécessaire : sans DATABASE_URL le serveur utilise un fichier SQLite local, et chaque application redémarre à la modification.

printf 'NODE_ENV=development\nADMIN_USERNAME=admin\nADMIN_PASSWORD=change-me\nNEXT_PUBLIC_BASE_API_URL=http://localhost:3010/api\n' > .env
yarn dev                                       # API :3010, administration :3000, site :3020

Tout le reste pour les contributeurs : CONTRIBUTING.md.

Ensuite

• La documentation sous forme de site, avec la référence de l’API et un playground : vocab-bloom-hub.com.
• Le mettre sur un serveur : docs/deployment/ — TLS et reverse proxy, systemd / PM2, mises à niveau.
• La base de données : docs/database.md — prérequis Postgres, migrations, sauvegardes, taille.
• Tous les réglages : docs/environment.md.
• Métriques et logs : docs/observability.md — Prometheus et Grafana en une commande, ou les vôtres.
• Lire les données : docs/api.md, les SDK Node.js et Python.

---