Standalone Docker

Use this path to run Echo on its own – evaluation, integration testing, or any environment that doesn't need the rest of the Oz API stack.

Shared concepts (authentication, endpoints, configuration reference) can be found on the parent page.

Prerequisites

• Docker Engine with Compose v2.20.3 or newer.

• If you want Echo to accept tokens issued by the main Oz API: the Oz platform's public key (jwt-api.pub), obtained from Oz Forensics.

1

Prepare a working directory and secrets

mkdir -p echo-deploy && cd echo-deploy

# Echo's own token-signing key (self-generated, per-deployment)
openssl rand -base64 129 | tr -d '
' > jwt.key

# At least one login account, TOML format: "email" = "password"
echo '"[e-mail]" = "change-me"' > users.toml

# Static bearer tokens (optional), TOML format: "email" = "token1,token2"
echo '"[e-mail]" = "some-long-random-token"' > static_tokens.toml

# If accepting tokens from the main Oz API, place the provided public key here:
# cp /path/to/provided/jwt-api.pub ./jwt-api.pub

users.toml and static_tokens.toml define who is allowed to authenticate against Echo directly.

docker-compose.yaml

services:
  echo:
    image: ozforensics/echo:<version>          # ask Oz Forensics for the current tag
    container_name: echo
    restart: unless-stopped
    environment:
      MONGODB_URL: "mongodb://root:${MONGO_PASSWORD}@echo-mongo:27017/"
      MONGODB_DB_NAME: "echo"
      QUERY_LIMIT: "100"
      PORT: "8010"
      LOG_LEVEL: "info"
      GET_SESSIONS_RATE_LIMIT: "100"
      ACCESS_TOKEN_EXPIRE_MINUTES: "120"
      OZ_JWT_KEY_PATH: "/app/keys/jwt.key"
      OZ_API_JWT_KEY_PATH: "/app/keys/jwt-api.pub"   # omit if not used
      USERS_TOML_PATH: "/app/users/users.toml"
      STATIC_TOKENS_TOML_PATH: "/app/users/static_tokens.toml"
    ports:
      - "8010:8010"
    volumes:
      - ./jwt.key:/app/keys/jwt.key:ro
      - ./jwt-api.pub:/app/keys/jwt-api.pub:ro       # omit if not used
      - ./users.toml:/app/users/users.toml:ro
      - ./static_tokens.toml:/app/users/static_tokens.toml:ro
    depends_on:
      echo-mongo:
        condition: service_healthy

  echo-mongo:
    image: mongo:7.0.12-jammy
    container_name: echo-mongo
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
      MONGO_INITDB_DATABASE: mongo
    command: ["--wiredTigerCacheSizeGB=1"]
    healthcheck:
      test: echo 'db.runCommand("ping").ok' | mongosh localhost:27017/test --quiet
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - ./mongo-data:/data/db

Create a .env next to it with a real password:

MONGO_PASSWORD=<pick-a-strong-password>

2

Start

docker compose up -d

3

Verify

curl http://localhost:8010/livez     # {"status": "ok"}
curl http://localhost:8010/healthz   # {"status": "ok"} once Mongo is reachable
curl http://localhost:8010/version   # {"echo_version": "...", "mongodb_version": "..."}

Notes

• The container runs as non-root (uid/gid 1000).

• Default worker count is 16 (NUM_WORKERS in build/image env) – reduce it for a small evaluation box if needed by overriding the image's env variable.

• GET /api/event_sessions additionally requires the calling account to be listed in a service allowlist (SERVICE_USERS_TOML_PATH) – not shown above since it's optional; add it if you need query access. See configuration.