Environment Variables

API Service (Hono)

Variable	Required	Default	Purpose
NODE_ENV	No	development	development, production, or test.
POSTGRES_HOST	Yes	—	Postgres host. Combined with the vars below into the connection URL by src/lib/resolve-database-url.ts.
POSTGRES_PORT	No	5432	Postgres port.
POSTGRES_USER	Yes	—	Postgres user.
POSTGRES_PASSWORD	Yes	—	Postgres password.
POSTGRES_DB	Yes	—	Postgres database name.
REDIS_HOST	Yes	—	Redis host. Combined with the vars below into the connection URL by src/lib/resolve-redis-url.ts.
REDIS_PORT	No	6379	Redis port.
REDIS_USER	No	—	Redis ACL user (leave unset unless your deployment uses ACLs).
REDIS_PASSWORD	No	—	Redis password.
REDIS_TLS	No	—	Set to 1 or true to use rediss:// (TLS). Required for most managed Redis providers.
LIBRIS_INBOX_PATH	Yes	—	Directory watched for new book files
LIBRIS_LIBRARY_PATH	Yes	—	Directory for organized book storage
API_SECRET_KEY	Yes	—	Secret for token encryption (min 32 chars)
PORT	No	3000	Port the API server listens on
COOKIE_DOMAIN	No	—	Parent domain for auth cookie (e.g., .example.com). Leave empty when on a single domain.
MIGRATIONS_PATH	No	./migrations	Path to database migration files. Used by runMigrations() in bootstrap.ts to auto-apply migrations on startup.
TRUST_PROXY_HEADERS	No	0	Set to 1 only when all requests pass through a trusted reverse proxy and its client IP headers should drive auth logging and rate limiting.
LOG_LEVEL	No	info	Minimum log level: trace, debug, info, warn, error, fatal. Applies to both stdout Pino output and the OpenTelemetry log pipeline.

DATABASE_URL and REDIS_URL are no longer read from the environment — the app assembles them from the split vars above. This gives docker-compose and the app a single source of truth; see docker-compose.dev.yml for the corresponding ${POSTGRES_USER:-libris} interpolation.

In development, Redis and cache use in-memory KV stores (no Redis connection needed).

OpenTelemetry

Libris supports exporting logs and traces via OpenTelemetry. The OTel SDK activates when OTEL_EXPORTER_OTLP_ENDPOINT is set. All configuration uses standard OTel environment variables — no custom Libris-specific vars are needed.

Variable	Required	Default	Purpose
OTEL_EXPORTER_OTLP_ENDPOINT	No	—	OTLP collector URL (e.g., http://alloy:4318). Enables OTel.
OTEL_SERVICE_NAME	No	libris	Service name in telemetry data
OTEL_EXPORTER_OTLP_PROTOCOL	No	http/protobuf	Protocol: http/protobuf, http/json, or grpc
OTEL_TRACES_EXPORTER	No	otlp	Trace exporter. Set to none to disable traces.
OTEL_LOGS_EXPORTER	No	otlp	Log exporter. Set to none to disable log export.
OTEL_METRICS_EXPORTER	No	otlp	Metrics exporter. Set to none to disable metrics.

When OTEL_EXPORTER_OTLP_ENDPOINT is not set, the OTel SDK does not initialize and adds zero overhead. Logs still flow to stdout via Pino regardless of OTel configuration.

Frontend (Vue SPA)

In production, the SPA is served by the Hono backend from the same origin — no frontend-specific configuration is needed. API requests use relative URLs (/api/*).

In development, the Vite dev server runs on port 3100 and proxies /api/* requests to the backend on port 3000 via its built-in proxy.

Metadata Sources

The Hardcover API token for metadata enrichment is stored in the database via Settings > Connections, not as an env var. It is optional — if not configured, external metadata enrichment is skipped during ingestion.

Source	Key type	Where to get it
Hardcover	Bearer token	hardcover.app/account/api

Test Environment

Variable	Value	Purpose
POSTGRES_HOST	localhost	Isolated test DB
POSTGRES_PORT	5433	Test Postgres port (non-standard to avoid clashing with dev)
POSTGRES_USER	libris_test
POSTGRES_PASSWORD	libris_test
POSTGRES_DB	libris_test
REDIS_HOST	localhost	Isolated test Redis
REDIS_PORT	6380	Test Redis port (non-standard)
LIBRIS_INBOX_PATH	/tmp/test-inbox	Ephemeral inbox
LIBRIS_LIBRARY_PATH	/tmp/test-library	Ephemeral library
E2E_TEST	1	Set to "1" to enable. Disables rate limiting, allows __test/ routes, and relaxes auth checks. Cannot be used with NODE_ENV=production.
E2E_API_KEY	(auto-generated)	Auto-generated by global-setup.ts (not user-provided). Seeds an API key via /api/auth/setup before tests run.

See .env.test.example for a complete template. Note that NUXT_SESSION_PASSWORD in that file is unused by any service code and can be safely omitted.