Vocab Bloom Hub

⚡ Primeros pasos

Tres opciones para empezar, de la más rápida a la más flexible. Todas terminan con el panel de administración, la API y el diccionario cargados: con Docker en http://localhost:3241 y http://localhost:3240, o sin él en http://localhost:3000 y http://localhost:3010.

1. Ejecutar las imágenes publicadas

Sin necesidad de clonar el repositorio — una carpeta, dos archivos, 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

Abre .env y define dos contraseñas: ADMIN_PASSWORD (el acceso de administración) y POSTGRES_PASSWORD (la base de datos incluida). A continuación:

docker compose up -d

El primer inicio descarga el diccionario y lo importa (tarda unos minutos). GET /api/ready responde 503 mientras se procesa y 200 una vez finalizado; luego inicia sesión con ADMIN_USERNAME / ADMIN_PASSWORD definidos en .env.

curl -s localhost:3240/api/ready            # {"status":"ok"}
curl -s localhost:3240/api/v1/words/run     # el diccionario responde

# búsqueda: entradas que coinciden con un término, la mejor coincidencia primero
curl -s 'localhost:3240/api/v1/search?search=run&limit=5'
# lo mismo, incluyendo significados, ejemplos y traducciones
curl -s 'localhost:3240/api/v1/search/detailed?search=run&with_meanings=true'

Consejo

Para fijar una versión específica en lugar de la compilación de desarrollo de main, define VBH_TAG=1.3.0 en .env. Para habilitar el sitio web (documentación, referencia de la API, playground y páginas de palabras) en http://localhost:3242, define COMPOSE_PROFILES=db,site.

2. Ejecutar desde el repositorio

El mismo archivo compose, compilado directamente desde el código fuente — para un fork o un cambio no publicado:

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
cp .env.example .env                           # define las mismas dos contraseñas
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

3. Ejecutar sin Docker

Una ejecución en producción directamente en la propia máquina: Node.js 22.13+, Yarn 4 (corepack enable) y una instancia de PostgreSQL accesible (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 en :3010, administración en :3000; el diccionario se importa automáticamente en el primer inicio
yarn site:build && yarn start:site             # sitio web en :3020, opcional, en otra terminal

Para desplegar detrás de un dominio y TLS, con systemd o PM2: docs/deployment/.

Para desarrollo

No se necesita una base de datos: sin DATABASE_URL el servidor utiliza un archivo SQLite local, y cada aplicación se recarga automáticamente ante cualquier cambio.

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 en :3010, administración en :3000, sitio web en :3020

Importante

Carga el diccionario desde Managing → Datasets → Import en el panel de administración.

Toda la información adicional para colaborar: CONTRIBUTING.md.

Siguiente

Con PostgreSQL, añade otro diccionario desde Managing → Datasets → How to install: la descarga en el servidor es la opción predeterminada; la carga manual es la alternativa. OpenGloss necesita los seis archivos Parquet (unos 1,32 GB). Fuentes, licencias, forks y límites de la conversión: datasets.md.

Editar esta página en GitHub