Configuration

This page lists every setting that controls the Dokimos server, so you can wire it up to your database, lock down writes, and tune the background workers.

You configure the server with environment variables. The defaults run out of the box with docker compose up, so you only set what you need to change.

Quick start

For local development you set nothing. Start the server with the bundled PostgreSQL:

docker compose up

To connect to your own database and require an API key for writes, set five variables:

export DB_HOST=your-postgres-host
export DB_NAME=dokimos
export DB_USERNAME=dokimos
export DB_PASSWORD=your-secure-password
export DOKIMOS_API_KEY=your-secret-key

The rest of this page explains each variable and shows full example configurations.

Environment variables

Database connection

Variable	Description	Default
DB_HOST	PostgreSQL hostname	localhost
DB_PORT	PostgreSQL port	5432
DB_NAME	Database name	dokimos
DB_USERNAME	Database username	dokimos
DB_PASSWORD	Database password	dokimos

Server settings

Variable	Description	Default
SERVER_PORT	HTTP port to listen on	8080
DOKIMOS_API_KEY	API key for write operations	(disabled)
DOKIMOS_ENCRYPTION_KEY	Passphrase used to encrypt inline LLM connection keys at rest. Required only if you store an inline apiKey on a connection.	(disabled)

Server side judge

These variables tune the background worker that scores LLM judge jobs. The defaults work for most deployments, so change them only if you need to.

Variable	Description	Default
DOKIMOS_JUDGE_POLL_INTERVAL_MS	How often the worker polls for pending judge jobs	5000
DOKIMOS_JUDGE_MAX_ATTEMPTS	Retry ceiling for a judge job before it fails	3
DOKIMOS_JUDGE_PAGE_SIZE	Items scored per database transaction	50

Traces and online evals

These variables control production trace retention and the online eval worker.

Variable	Description	Default
DOKIMOS_TRACE_RETENTION_DAYS	Days an ingested trace is kept before the sweeper deletes it	30
DOKIMOS_TRACE_SWEEP_INTERVAL_MS	How often the retention sweeper runs	3600000
DOKIMOS_TRACE_EVAL_POLL_INTERVAL_MS	How often the worker polls for pending trace eval jobs	5000
DOKIMOS_TRACE_EVAL_MAX_ATTEMPTS	Retry ceiling for a trace eval job before it fails	3
DOKIMOS_TRACE_EVAL_CLAIM_TIMEOUT_MS	How long a claimed trace eval job can run before it is requeued	600000

Logging

Variable	Description	Default
LOG_LEVEL	Application log level	INFO
SQL_LOG_LEVEL	Hibernate SQL logging level	WARN

Database setup

PostgreSQL requirements

The server needs PostgreSQL 14 or higher. Flyway manages the schema for you and runs the migrations on startup.

Connection string format

The server builds the JDBC URL from the database variables:

jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME}

To pass extra connection parameters, set the Spring datasource URL directly instead:

export SPRING_DATASOURCE_URL=jdbc:postgresql://host:5432/dokimos?ssl=true&sslmode=require

Create the database

To use an existing PostgreSQL instance, create the database and user first:

CREATE DATABASE dokimos;
CREATE USER dokimos WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE dokimos TO dokimos;

-- Connect to the dokimos database and grant schema permissions
\c dokimos
GRANT ALL ON SCHEMA public TO dokimos;

Schema migrations

Migrations run automatically on startup. Flyway does three things:

• Creates tables if they do not exist.
• Applies new migrations in order.
• Never drops or modifies existing data destructively.

API key configuration

Set DOKIMOS_API_KEY to require authentication on write operations:

export DOKIMOS_API_KEY=your-secret-key-here

Read operations stay open. See Authentication for how the API key check works.

Port and host binding

Change the port

export SERVER_PORT=3000

Bind to all interfaces

The server binds to all interfaces (0.0.0.0) by default.

To restrict it to localhost during local development, map the port with Docker:

ports:
  - "127.0.0.1:8080:8080"

Example configurations

Local development

For local development, set nothing. The bundled docker-compose provides PostgreSQL:

docker compose up

Development with an API key

To test authentication locally, set the API key before you start:

export DOKIMOS_API_KEY=dev-secret-key
docker compose up

Production with an external database

To connect to a managed PostgreSQL instance, set the database variables and an API key:

export DB_HOST=your-postgres-host.amazonaws.com
export DB_PORT=5432
export DB_NAME=dokimos_prod
export DB_USERNAME=dokimos_app
export DB_PASSWORD=secure-password-here
export DOKIMOS_API_KEY=production-api-key
export LOG_LEVEL=WARN

docker run -d \
  -p 8080:8080 \
  -e DB_HOST -e DB_PORT -e DB_NAME -e DB_USERNAME -e DB_PASSWORD \
  -e DOKIMOS_API_KEY -e LOG_LEVEL \
  dokimos-server

CI/CD environment

To point the client at a shared internal server from CI, set these variables in your pipeline:

# In your CI environment
export DOKIMOS_SERVER_URL=https://dokimos.internal.company.com
export DOKIMOS_PROJECT_NAME=my-llm-app
export DOKIMOS_API_KEY=${{ secrets.DOKIMOS_API_KEY }}

Health checks

The server exposes two health endpoints:

• /actuator/health reports overall health status.
• /actuator/info reports application info.

Use these for load balancer health checks and container orchestration:

curl http://localhost:8080/actuator/health

Spring Boot properties

The server is a Spring Boot application, so you can set any Spring Boot configuration property. Common ones:

# Connection timeout
export SPRING_DATASOURCE_HIKARI_CONNECTION_TIMEOUT=30000

# Maximum pool size
export SPRING_DATASOURCE_HIKARI_MAXIMUM_POOL_SIZE=10

# Server request timeout
export SERVER_TOMCAT_CONNECTION_TIMEOUT=20000

See the Spring Boot documentation for the full list of properties.