Vocab Bloom Hub

⚡ Getting started

Three ways in, from the quickest to the most flexible. All of them end with the admin panel, the API and the dictionary loaded: under Docker on http://localhost:3241 and http://localhost:3240, without it on http://localhost:3000 and http://localhost:3010.

1. Run the published images

No checkout needed — one folder, two files, 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

Open .env and set two passwords: ADMIN_PASSWORD (the admin login) and POSTGRES_PASSWORD (the bundled database). Then:

docker compose up -d

The first start downloads the dictionary and imports it — a few minutes. GET /api/ready answers 503 until it is in and 200 after; then sign in with ADMIN_USERNAME / ADMIN_PASSWORD from .env.

curl -s localhost:3240/api/ready            # {"status":"ok"}
curl -s localhost:3240/api/v1/words/run     # the dictionary answers

# search: the entries matching a term, best match first
curl -s 'localhost:3240/api/v1/search?search=run&limit=5'
# the same with meanings, examples and translations
curl -s 'localhost:3240/api/v1/search/detailed?search=run&with_meanings=true'

Tip

To pin a release instead of the main development build, set VBH_TAG=1.0.0 in .env. To add the website (docs, API reference, playground, word pages) on http://localhost:3242, set COMPOSE_PROFILES=db,site.

2. Run from the repository

The same compose file, built from the sources — for a fork or an unpublished change:

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
cp .env.example .env                           # the same two passwords
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

3. Run without Docker

A production run on the machine itself: Node.js 22.13+, Yarn 4 (corepack enable) and a Postgres you can reach (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; the dictionary loads itself on the first start
yarn site:build && yarn start:site             # the website :3020, optional, in another terminal

Behind a domain and TLS, with systemd or PM2: docs/deployment/.

For development

No database needed: without DATABASE_URL the server uses a local SQLite file, and every app restarts on change.

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

Important

Load the dictionary with Import dictionary in the admin panel.

Everything else for contributors: CONTRIBUTING.md.

Next

Edit this page on GitHub