Docker Compose

Use this path if you run the full Oz API stack (api6) via Docker Compose. Echo is one of several services api6 brings up; this guide covers the Echo-specific parts of that process. It assumes you're already following api6's own README for the base stack – the steps below are the subset that matter for Echo.

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

Prerequisites

• Docker Compose v2.20.3 or newer (the compose files use the include: key)

• The api6 release contents laid out in an install directory, e.g., /opt/oz/api6.

• All commands below must be run from that install directory – cross-file service discovery (nginx → Echo → Mongo) depends on every compose invocation sharing the same default network, which Compose derives from the working directory

1

Make init scripts executable

API_DIR=/opt/oz/api6
find "$API_DIR/configs/" -name "*.sh" -exec chmod +x {} \;

2

Generate the Oz API JWT keypair

Echo uses the public half of this keypair to verify tokens issued by the main API.

openssl ecparam -name secp384r1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt \
  -out "$API_DIR/configs/api/keys/jwt/jwt.key"
openssl ec -in "$API_DIR/configs/api/keys/jwt/jwt.key" -pubout \
  -out "$API_DIR/configs/api/keys/jwt/jwt.pub"

3

Generate Echo's own signing key

This one is separate from the API keypair above – it's only used for Echo's own login/refresh tokens.

openssl rand -base64 129 | tr -d '
' > "$API_DIR/configs/echo/keys/jwt.key"

4

(Optional) Static Echo users/tokens

Edit these – empty by default:

• configs/echo/service.toml – comma-separated list of accounts allowed to call GET /api/event_sessions.

• configs/echo/static_tokens.toml – "email" = "token" pre-shared bearer tokens.

• configs/echo/users.toml – "email" = "password" login accounts.

5

Change default passwords before first run

At minimum, edit configs/env/mongo.env and set MONGO_PASS to something other than the shipped default – this is the credential Echo uses to reach its shared MongoDB.

6

Start the core API, then Echo

cd "$API_DIR"
docker compose -f ./docker/docker-compose-api-local-local.yml up -d      # or -local-s3.yml for S3 storage
docker compose -f ./docker/docker-compose-echo-maxwell.yml up -d

This brings up three containers: api6-echo, api6-mongo (shared with Maxwell), and api6-maxwell.

How Echo is reached

Echo does not publish a host port in this setup. It's reverse-proxied through api6-nginx, controlled by two variables in configs/env/nginx.env:

ECHO_ENABLE="Yes"
ECHO_HOST="api6-echo"

To disable Echo, comment out both lines (confirm it with Oz Forensics support first, since it's treated as an essential component).

Verification

Through Nginx, from outside:

curl https://<your-api-host>/api/event_sessions/... # via whatever path/port your nginx is configured with

Directly, from inside the Docker network (useful for a quick sanity check without going through nginx/TLS):

docker exec -it api6-echo curl -s http://localhost:8010/healthz