Development Environment
Local setup, environment variables, and running the API.
Prerequisites
- Node.js 24.x — from the service repo root:
nvm use(reads.nvmrc) NODE_AUTH_TOKEN/ GitHub Packages — for@sequel-de/*installs. Prefernpm config set //npm.pkg.github.com/:_authToken …locally. Docker/CI inject the token only duringnpm ci(see service root README).- Docker and Docker Compose — PostgreSQL, Redis, LedgerMatch, Keycloak
- Embeddings — LedgerMatch needs embeddings:
- Ollama (default in Docker) — no API key; Compose pulls
mxbai-embed-large - OpenAI — set
OPENAI_API_KEYandEMBEDDING_PROVIDER=openaifor LedgerMatch
- Ollama (default in Docker) — no API key; Compose pulls
Option A: Full Docker (recommended)
cp .env.example .env
# Set EBICS_KEY_ENCRYPTION_KEY (32+ chars) if you use EBICS
export NODE_AUTH_TOKEN=ghp_… # required to build the API image
docker compose up --build
- API: http://localhost:8000
- Swagger: http://localhost:8000/api/docs
The payment-reconciler container runs migrations, Keycloak realm setup, seed, and npm run start:dev.
Option B: Hybrid (Docker for deps, local API)
docker compose up -d payment-reconciler-db ledger-match-db redis keycloak keycloak-db ollama ledger-match
cp .env.example .env
# DATABASE_URL → localhost:5433, REDIS_URL → localhost:6379
# Ensure GitHub Packages auth is configured (npm config set …/_authToken …)
nvm use
npm install
npm run prisma:generate
npm run prisma:migrate
npm run keycloak:setup-realm # Optional
npm run prisma:seed # Optional
npm run start:dev
Environment variables
| Variable | Required | Description |
|---|---|---|
| DATABASE_URL | Yes | PostgreSQL (e.g. postgresql://postgres:postgres@localhost:5433/paymentreconciler) |
| REDIS_URL | Yes | Redis for BullMQ and cache |
| LEDGER_MATCH_API_URL | Yes | LedgerMatch REST URL (e.g. http://localhost:9000) |
| JWT_SECRET | Yes | JWT signing secret (dev: any string) |
| AUTH_MODE | No | keycloak (typical), both, or other — see .env.example / README |
| EBICS_KEY_ENCRYPTION_KEY | For EBICS | 32+ character key wrapping EBICS key material at rest |
| NODE_AUTH_TOKEN | Install/build | GitHub Packages auth for @sequel-de/* (CI/Docker secret; not Nest runtime) |
| OPENAI_API_KEY | When using OpenAI | LedgerMatch embeddings if EMBEDDING_PROVIDER=openai |
| KEYCLOAK_URL | When AUTH_MODE=keycloak | Keycloak base URL |
| KEYCLOAK_REALM | No | Default: sequel |
| KEYCLOAK_CLIENT_ID | No | Default: payment-reconciler-client |
| PORT | No | API port (default: 8000) |
| LOG_LEVEL | No | info, debug, etc. |
| CACHE_ENABLED | No | Enable Redis cache (default: true) |
See .env.example for the full list.
Useful commands
| Command | Purpose |
|---|---|
npm run prisma:studio | Open Prisma Studio |
npm run prisma:migrate | Run migrations (dev) |
npm run prisma:migrate:deploy | Run migrations (prod/deploy) |
npm run prisma:seed | Seed initial data |
npm run keycloak:setup-realm | Configure Keycloak realm and client |
npm run start:dev | Start API with watch |
npm test | Unit tests |
npm run test:e2e | E2E tests (requires Redis + PostgreSQL) |
Swagger and health
- Swagger UI — http://localhost:8000/api/docs
- Health — http://localhost:8000/api/health
- LedgerMatch health — http://localhost:8000/api/health/ledger-match
Next steps
- Authentication — How to get a token and call the API
- Tenants — Create tenants and environments
- Data Sources — Stripe, EBICS, SFTP, CSV
- Reconciliation — Reconciliation flow