⚡ Primeiros passos

Três opções para começar, da mais rápida à mais flexível. Todas terminam com o painel de administração, a API e o dicionário carregados: com Docker em http://localhost:3241 e http://localhost:3240, ou sem ele em http://localhost:3000 e http://localhost:3010.

1. Executar as imagens publicadas

Sem necessidade de clonar o repositório — uma pasta, dois ficheiros, 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 ficheiro .env e defina duas palavras-passe: ADMIN_PASSWORD (o acesso de administração) e POSTGRES_PASSWORD (a base de dados incluída). A seguir:

docker compose up -d

A primeira inicialização descarrega o dicionário e importa-o — demora alguns minutos. GET /api/ready responde 503 enquanto a importação decorre e 200 ao terminar; depois inicie sessão com ADMIN_USERNAME / ADMIN_PASSWORD definidos no .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 a um termo, a melhor correspondência 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'

2. Executar a partir do repositório

O mesmo ficheiro compose, compilado diretamente a partir do código-fonte — 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                           # defina as mesmas duas palavras-passe
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

3. Executar sem Docker

Uma execução em produção diretamente na própria máquina: Node.js 22.13+, Yarn 4 (corepack enable) e um PostgreSQL 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 na primeira inicialização
yarn site:build && yarn start:site             # o site :3020, opcional, noutro terminal

Para implementar atrás de um domínio e TLS, com systemd ou PM2: docs/deployment/.

Para desenvolvimento

Não é necessária base de dados: sem DATABASE_URL, o servidor usa um ficheiro SQLite local, e cada aplicação reinicia automaticamente ao ser alterada.

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

Tudo 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.

No PostgreSQL, adicione outro dicionário em Managing → Datasets → How to install: o download no servidor é o padrão; o envio manual é a alternativa. O OpenGloss precisa dos seis arquivos Parquet (cerca de 1,32 GB). Fontes, licenças, forks e limites de conversão: datasets.md.

---