⚡ Erste Schritte

Drei Wege, vom schnellsten zum flexibelsten. Alle enden mit dem Admin-Panel, der API und dem geladenen Wörterbuch: mit Docker auf http://localhost:3241 und http://localhost:3240, ohne Docker auf http://localhost:3000 und http://localhost:3010.

1. Die veröffentlichten Images starten

Kein Checkout nötig — ein Ordner, zwei Dateien, 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

Öffnen Sie die .env und setzen Sie zwei Passwörter: ADMIN_PASSWORD (die Admin-Anmeldung) und POSTGRES_PASSWORD (die mitgelieferte Datenbank). Dann:

docker compose up -d

Der erste Start lädt das Wörterbuch herunter und importiert es — einige Minuten. GET /api/ready antwortet solange mit 503 und danach mit 200; dann melden Sie sich mit ADMIN_USERNAME / ADMIN_PASSWORD aus der .env an.

curl -s localhost:3240/api/ready            # {"status":"ok"}
curl -s localhost:3240/api/v1/words/run     # das Wörterbuch antwortet

# Suche: die passenden Einträge, der beste Treffer zuerst
curl -s 'localhost:3240/api/v1/search?search=run&limit=5'
# dasselbe mit Bedeutungen, Beispielen und Übersetzungen
curl -s 'localhost:3240/api/v1/search/detailed?search=run&with_meanings=true'

Tipp

Um ein Release statt des Entwicklungs-Builds main zu pinnen, setzen Sie VBH_TAG=1.0.0 in der .env. Um die Website (Dokumentation, API-Referenz, Playground, Wortseiten) auf http://localhost:3242 hinzuzufügen, setzen Sie COMPOSE_PROFILES=db,site.

2. Aus dem Repository starten

Dieselbe Compose-Datei, aus den Quellen gebaut — für einen Fork oder eine unveröffentlichte Änderung:

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
cp .env.example .env                           # dieselben zwei Passwörter
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

3. Ohne Docker starten

Ein Produktivstart direkt auf der Maschine: Node.js 22.13+, Yarn 4 (corepack enable) und ein erreichbares Postgres (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, Admin :3000; das Wörterbuch lädt sich beim ersten Start selbst
yarn site:build && yarn start:site             # die Website :3020, optional, in einem zweiten Terminal

Hinter einer Domain und TLS, mit systemd oder PM2: docs/deployment/.

Für die Entwicklung

Keine Datenbank nötig: ohne DATABASE_URL nutzt der Server eine lokale SQLite-Datei, und jede App startet bei Änderungen neu.

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, Admin :3000, Website :3020

Wichtig

Laden Sie das Wörterbuch mit Import dictionary im Admin-Panel.

Alles Weitere für Mitwirkende: CONTRIBUTING.md.

Weiter

Die Dokumentation als Website, mit der API-Referenz und einem Playground: vocab-bloom-hub.com.
Auf einen Server bringen: docs/deployment/ — TLS und Reverse-Proxy, systemd / PM2, Upgrades.
Die Datenbank: docs/database.md — Postgres-Anforderungen, Migrationen, Backups, Größe.
Jede Einstellung: docs/environment.md.
Metriken und Logs: docs/observability.md — Prometheus und Grafana mit einem Befehl, oder Ihre eigenen.
Die Daten lesen: docs/api.md, die SDKs für Node.js und Python.

Diese Seite auf GitHub bearbeiten