Self-Hosting EpistemicDB

Docker Compose (recommended)

Create a docker-compose.yml:

version: '3.9'
services:
  epistemicdb:
    image: epistemicdb/server:0.1.0
    ports:
      - "5433:5433"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/epistemicdb
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - EDB_ADMIN_KEY=${EDB_ADMIN_KEY}
      - EDB_PORT=5433
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_DB: epistemicdb
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - edb_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  edb_data:

Start with:

docker compose up -d

Building from source

git clone <repo> && cd epistemicdb
npm ci
npm run build -w packages/eql
npm run build -w packages/server
docker build . -t epistemicdb/server:0.1.0

Environment variables

Variable	Required	Default	Description
DATABASE_URL	Yes	—	PostgreSQL connection string
EDB_PORT	No	5433	Server port
OPENAI_API_KEY	No	—	For embedding generation
EDB_ADMIN_KEY	No	—	Admin API key for bootstrapping

Health check

curl http://localhost:5433/health

Returns:

{
  "status": "ok",
  "version": "0.1.0",
  "uptime_seconds": 42,
  "watch_subscriptions": 0
}

API endpoints

Method	Path	Auth	Description
POST	/query	Yes	Execute EQL
POST	/query/validate	Yes	Validate EQL
GET	/schema	No	Schema info
GET	/health	No	Health check
GET	/metrics	No	Prometheus metrics
POST	/projects	Admin	Create project
GET/DELETE	/projects/:id	Admin	Manage project
POST/GET/PATCH/DELETE	/ko	Yes	KO CRUD
POST/DELETE/GET	/watch	Yes	HTTP subscriptions
WS	/watch/ws	Query	WebSocket subscriptions