Instalación

Esta guía lleva el servidor de cero a respondiendo en localhost:5000.

Requisitos

• Bun ≥ 1.4
• PostgreSQL ≥ 14 (o un contenedor, p. ej. Podman/Docker)
• psql para aplicar los triggers

1. Instalar dependencias

bun install

2. Variables de entorno

cp .env.example .env

Edita .env; como mínimo DATABASE_URL y los secretos (BOLETO_HMAC_SECRET, REFRESH_TOKEN_SECRET). La tabla completa de variables está en Variables de entorno.

3. Esquema de base de datos

bunx --bun drizzle-kit push   # dev: sincroniza el schema
# o, con migraciones versionadas:
bunx --bun drizzle-kit generate && bunx --bun drizzle-kit migrate

Siempre después de push/migrate, aplicar los triggers (integridad cross-evento e inmutabilidad de la bitácora):

psql "$DATABASE_URL" -f src/db/triggers.sql
# en podman:
podman exec -i <contenedor> psql -U <usuario> -d <db> < src/db/triggers.sql

Nota

Los tests e2e usan una base de datos separada (pisa_api_test); ver Tests.

4. Arrancar

bun run dev

Salida esperada:

[cron] programado * * * * *
[cron] programado */2 * * * *
[cron] programado 0 6 * * *
[cron] programado 0 3 * * *
🦊 Elysia is running at localhost:5000
Manual at localhost:5000/
Docs at localhost:5000/openapi

5. Verificar

curl http://localhost:5000/health
# {"status":"ok","db":"ok","uptimeSegundos":3}

/health sondea además la base de datos (SELECT 1 con tope de 2 s): si la DB no contesta responde 503 {"status":"degradado"} y el motivo queda en el log. Sirve para sondeos de orquestación y no consume rate-limit.

Documentación

URL	Qué es
/	Este manual (si docs/dist está construido)
/openapi	Referencia interactiva de endpoints (Scalar)
/openapi/json	La especificación OpenAPI en JSON
/llms.txt	Índice para LLMs (con llms-full.txt y llms-small.txt); ver llms.txt para LLMs

Para compilar este sitio: cd docs && bun install && bun run build (ver Despliegue).

Siguiente paso

→ Autenticación y roles