> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/guides/administrator-guide/telemetry/echo-oz-telemetry-receiver/standalone-docker.md).

# 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](/oz-knowledge/guides/administrator-guide/telemetry/echo-oz-telemetry-receiver.md).

### 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.

{% stepper %}
{% step %}

### Prepare a working directory and secrets

```shellscript
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 '"admin@example.com" = "change-me"' > users.toml

# Static bearer tokens (optional), TOML format: "email" = "token1,token2"
echo '"admin@example.com" = "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**

```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>
```

{% endstep %}

{% step %}

### Start

```shellscript
docker compose up -d
```

{% endstep %}

{% step %}

### Verify

```shellscript
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": "..."}
```

{% endstep %}
{% endstepper %}

### 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](/oz-knowledge/guides/administrator-guide/telemetry/echo-oz-telemetry-receiver.md#configuration).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge/guides/administrator-guide/telemetry/echo-oz-telemetry-receiver/standalone-docker.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.