⚡ Быстрый старт

Три пути, от самого быстрого к самому гибкому. Все заканчиваются админкой, API и загруженным словарём: в Docker на http://localhost:3241 и http://localhost:3240, без него на http://localhost:3000 и http://localhost:3010.

1. Запуск готовых образов

Без клонирования — одна папка, два файла, 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

Откройте .env и задайте два пароля: ADMIN_PASSWORD (вход в админку) и POSTGRES_PASSWORD (встроенная база). Затем:

docker compose up -d

Первый запуск скачивает словарь и импортирует его — несколько минут. GET /api/ready отвечает 503, пока идёт загрузка, и 200 после; затем войдите с ADMIN_USERNAME / ADMIN_PASSWORD из .env.

curl -s localhost:3240/api/ready            # {"status":"ok"}
curl -s localhost:3240/api/v1/words/run     # словарь отвечает

# поиск: статьи по запросу, лучшее совпадение первым
curl -s 'localhost:3240/api/v1/search?search=run&limit=5'
# то же со значениями, примерами и переводами
curl -s 'localhost:3240/api/v1/search/detailed?search=run&with_meanings=true'

2. Запуск из репозитория

Тот же compose-файл, собранный из исходников — для форка или неопубликованного изменения:

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
cp .env.example .env                           # те же два пароля
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

3. Запуск без Docker

Продуктовый запуск прямо на машине: Node.js 22.13+, Yarn 4 (corepack enable) и доступный 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, админка :3000; словарь загрузится сам при первом запуске
yarn site:build && yarn start:site             # сайт :3020, по желанию, в другом терминале

За доменом и TLS, под systemd или PM2: docs/deployment/.

Для разработки

База не нужна: без DATABASE_URL сервер использует локальный файл SQLite, а все приложения перезапускаются при изменениях.

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, админка :3000, сайт :3020

Всё остальное для контрибьюторов: CONTRIBUTING.md.

Дальше

• Документация в виде сайта, со справочником API и песочницей: vocab-bloom-hub.com.
• На сервер: docs/deployment/ — TLS и обратный прокси, systemd / PM2, обновления.
• База данных: docs/database.md — требования к Postgres, миграции, бэкапы, размер.
• Все настройки: docs/environment.md.
• Метрики и логи: docs/observability.md — Prometheus и Grafana одной командой или свои.
• Чтение данных: docs/api.md, SDK для Node.js и Python.

---