Skip to main content

Deployment

This page shows you how to run the Dokimos server, from your laptop to production. One pre-built Docker image works everywhere. You add configuration as your needs grow.

Run it locally​

Start here to try things out or for individual use. Two commands:

curl -O https://raw.githubusercontent.com/dokimos-dev/dokimos/master/docker-compose.yml
docker compose up -d

Open http://localhost:8080. Done.

You now have:

  • A PostgreSQL database with persistent storage.
  • The Dokimos server on port 8080.
  • No authentication (open access).

Run it for your team​

Run the server on a shared machine or VM so your team sees the same results. Two steps: turn on an API key, then pin a version.

Turn on API key authentication​

Add one line to docker-compose.yml. It protects write operations, so only clients with the key can submit results. Read operations stay open.

# docker-compose.yml
services:
  server:
    image: ghcr.io/dokimos-dev/dokimos-server:latest
    environment:
      # ... other env vars ...
      DOKIMOS_API_KEY: your-secret-key  # Add this line

Restart the server, then point your clients at it and pass the key:

DokimosServerReporter reporter = DokimosServerReporter.builder()
    .serverUrl("http://your-team-server:8080")
    .projectName("my-project")
    .apiKey("your-secret-key")
    .build();

See Authentication for the full setup.

Pin a version​

The latest tag moves. Pin a release so upgrades never surprise you:

services:
  server:
    image: ghcr.io/dokimos-dev/dokimos-server:0.20.0  # Pin version

Run it in production​

For production, swap in a managed database and put a load balancer in front for TLS.

Use a managed database​

Replace the bundled PostgreSQL with a managed service (for example AWS RDS). Set the DB_* variables to point at it:

# docker-compose.yml (production)
services:
  server:
    image: ghcr.io/dokimos-dev/dokimos-server:0.20.0
    ports:
      - "8080:8080"
    environment:
      DB_HOST: your-rds-endpoint.amazonaws.com
      DB_PORT: 5432
      DB_NAME: dokimos
      DB_USERNAME: dokimos
      DB_PASSWORD: ${DB_PASSWORD}  # Read from an environment variable
      DOKIMOS_API_KEY: ${DOKIMOS_API_KEY}

For TLS, put a cloud load balancer in front (AWS ALB, GCP Load Balancer). It terminates TLS for you.

Run the container directly​

No Docker Compose? Run the image yourself and pass the same variables as flags:

docker run -d \
  --name dokimos-server \
  -p 8080:8080 \
  -e DB_HOST=your-postgres-host \
  -e DB_PORT=5432 \
  -e DB_NAME=dokimos \
  -e DB_USERNAME=your-user \
  -e DB_PASSWORD=your-password \
  -e DOKIMOS_API_KEY=your-api-key \
  ghcr.io/dokimos-dev/dokimos-server:0.20.0

Run it on Kubernetes​

Apply this manifest. It creates a Deployment with two replicas plus a LoadBalancer Service. Database password and API key come from a Secret named dokimos-secrets.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dokimos-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: dokimos-server
  template:
    metadata:
      labels:
        app: dokimos-server
    spec:
      containers:
      - name: server
        image: ghcr.io/dokimos-dev/dokimos-server:0.20.0
        ports:
        - containerPort: 8080
        env:
        - name: DB_HOST
          value: postgres-service
        - name: DB_NAME
          value: dokimos
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: dokimos-secrets
              key: db-password
        - name: DOKIMOS_API_KEY
          valueFrom:
            secretKeyRef:
              name: dokimos-secrets
              key: api-key
        livenessProbe:
          httpGet:
            path: /actuator/health
            port: 8080
          initialDelaySeconds: 30
        readinessProbe:
          httpGet:
            path: /actuator/health
            port: 8080
          initialDelaySeconds: 10
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "1000m"
---
apiVersion: v1
kind: Service
metadata:
  name: dokimos-server
spec:
  selector:
    app: dokimos-server
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

Health checks​

The server exposes two endpoints for load balancers and orchestrators:

  • /actuator/health is the liveness check.
  • /actuator/health/readiness is the readiness check.

Point your load balancer at the health path:

Health check path: /actuator/health
Interval: 30s
Timeout: 5s
Healthy threshold: 2
Unhealthy threshold: 3
For AI agentsView as Markdown