⚡ Primeiros passos
Três caminhos, do mais rápido ao mais flexível. Todos terminam com o painel de administração, a API e o dicionário carregado: com Docker em http://localhost:3241 e http://localhost:3240, sem ele em http://localhost:3000 e http://localhost:3010.
1. Rodar as imagens publicadas
Sem clonar nada — uma pasta, dois arquivos, 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
Abra o .env e defina duas senhas: ADMIN_PASSWORD (o login de administração) e
POSTGRES_PASSWORD (o banco incluído). Depois:
docker compose up -d
A primeira inicialização baixa o dicionário e o importa — alguns minutos. GET /api/ready
responde 503 enquanto isso e 200 ao terminar; então entre com ADMIN_USERNAME /
ADMIN_PASSWORD do .env.
curl -s localhost:3240/api/ready # {"status":"ok"}
curl -s localhost:3240/api/v1/words/run # o dicionário responde
# busca: os verbetes correspondentes, o melhor primeiro
curl -s 'localhost:3240/api/v1/search?search=run&limit=5'
# o mesmo com significados, exemplos e traduções
curl -s 'localhost:3240/api/v1/search/detailed?search=run&with_meanings=true'
Dica
Para fixar uma versão em vez da build main, defina VBH_TAG=1.0.0 no .env. Para
adicionar o site (documentação, referência da API, playground, páginas de palavras) em
http://localhost:3242, defina COMPOSE_PROFILES=db,site.
2. Rodar a partir do repositório
O mesmo arquivo compose, construído a partir das fontes — para um fork ou uma alteração não publicada:
git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
cp .env.example .env # as mesmas duas senhas
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
3. Rodar sem Docker
Uma execução de produção na própria máquina: Node.js 22.13+, Yarn 4 (corepack enable) e um
Postgres acessível (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, administração :3000; o dicionário carrega sozinho no primeiro arranque
yarn site:build && yarn start:site # o site :3020, opcional, em outro terminal
Atrás de um domínio e TLS, com systemd ou PM2: docs/deployment/.
Para desenvolvimento
Não precisa de banco de dados: sem DATABASE_URL o servidor usa um arquivo SQLite local, e cada
aplicação reinicia ao mudar.
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, administração :3000, site :3020
Importante
Carregue o dicionário com Import dictionary no painel de administração.
Todo o resto para contribuidores: CONTRIBUTING.md.
A seguir
- A documentação como site, com a referência da API e um playground: vocab-bloom-hub.com.
- Colocar em um servidor:
docs/deployment/— TLS e proxy reverso, systemd / PM2, atualizações. - O banco de dados:
docs/database.md— requisitos do Postgres, migrações, backups, tamanho. - Todas as configurações:
docs/environment.md. - Métricas e logs:
docs/observability.md— Prometheus e Grafana com um comando, ou os seus. - Ler os dados:
docs/api.md, os SDKs de Node.js e Python.