Docker deployment

Prerequisites

• Docker
• Docker Compose v2.0.0+
• Make (optional)
• 6 GB of RAM for the application (or ~3 GB using minimal mode)
• 14 GB of disk space

Get and run the demo

1. Clone the Demo repository:

   git clone https://github.com/open-telemetry/opentelemetry-demo.git
   

2. Change to the demo folder:

   cd opentelemetry-demo/
   

3. Start the demo¹:

   • Make
   • Docker

   make start
   

   docker compose --env-file .env --env-file .env.override \
     -f compose.yaml -f compose.full.yaml \
     -f compose.observability.yaml -f compose.extras.yaml \
     up --force-recreate --remove-orphans --detach
   

   Deployment modes

   The demo supports several deployment modes. The default make start runs the full demo with all services and the observability stack. Other modes let you reduce resource usage or exclude certain components:

   Mode	Make target	Description
   Full	make start	All services and observability backends (default)
   Minimal	make start-minimal	Excludes Kafka and its dependent services (accounting, fraud-detection, kafka), reducing memory usage to ~3 GB
   No observability	make start-no-o11y	All services without the observability backends (Jaeger, Grafana, Prometheus, OpenSearch)
   Minimal, no observability	make start-minimal-no-o11y	Minimal services without the observability backends
   Profiling	make start-profiling	Full mode with an eBPF profiler and the Firepit UI for profiling data
   Agentic	make start-agentic	Full mode with an AI agent, MCP server, and chatbot for interacting with the demo

   For example, to start the demo in minimal mode:

   • Make
   • Docker

   make start-minimal
   

   docker compose --env-file .env --env-file .env.override \
     -f compose.yaml -f compose.observability.yaml -f compose.extras.yaml \
     up --force-recreate --remove-orphans --detach
   

4. (Optional) Run telemetry sanity tests:

   The demo includes a suite of telemetry sanity tests that verify each service is producing traces, metrics, and logs and that they reach the expected backends (Jaeger, Prometheus, OpenSearch). For details, see test/telemetry/README.md.

   Test scope	Make target	Starts
   Full	make run-telemetry-tests	Full deployment (make start)
   Minimal	make run-telemetry-tests-minimal	Minimal deployment (make start-minimal)
   Agentic	make run-telemetry-tests-agentic	Agentic deployment (with agent, MCP, and chatbot)

   Each target builds the test image from ./test/telemetry, starts the corresponding deployment, runs the tests, and then tears down the demo.

   • Make
   • Docker

   make run-telemetry-tests
   

   # The demo must be running before you start the tests.
   docker build -t opentelemetry-demo-telemetry-tests ./test/telemetry
   docker run --rm --network opentelemetry-demo \
     --env-file .env --env-file .env.override \
     -e TEST_SCOPE=full \
     opentelemetry-demo-telemetry-tests
   

Verify the web store and Telemetry

Once the images are built and containers are started you can access:

• Web store: http://localhost:8080/
• Flagd configurator UI: http://localhost:8080/feature
• Telemetry documentation (generated by Weaver): http://localhost:8080/telemetry/

The following are available when the observability stack is running (i.e., not in *-no-o11y modes):

• Grafana: http://localhost:8080/grafana/
• Jaeger UI: http://localhost:8080/jaeger/ui/
• OpAMP UI: http://localhost:8080/opamp/

The following are available only in specific deployment modes:

• Firepit UI (profiling mode): http://localhost:8080/profiles/
• Chatbot (agentic mode): http://localhost:8080/chatbot/

Changing the demo’s primary port number

By default, the demo application will start a proxy for all browser traffic bound to port 8080. To change the port number, set the ENVOY_PORT environment variable before starting the demo.

• For example, to use port 8081¹:

  • Make
  • Docker

  ENVOY_PORT=8081 make start
  

  ENVOY_PORT=8081 docker compose --env-file .env --env-file .env.override \
    -f compose.yaml -f compose.full.yaml \
    -f compose.observability.yaml -f compose.extras.yaml \
    up --force-recreate --remove-orphans --detach
  

Bring your own backend

Likely you want to use the web store as a demo application for an observability backend you already have (e.g., an existing instance of Jaeger, Zipkin, or one of the vendors of your choice).

OpenTelemetry Collector can be used to export telemetry data to multiple backends. By default, the collector in the demo application merges the configuration from the following files (in order):

• otelcol-config.yml — base receivers, processors, and pipelines
• otelcol-config-full.yml — Kafka and PostgreSQL metric receivers (full mode)
• otelcol-config-observability.yml — Jaeger, Prometheus, and OpenSearch exporters (when using the observability stack)
• otelcol-config-extras.yml — empty stub for customizations, always loaded last

To add your backend, open the file src/otel-collector/otelcol-config-extras.yml with an editor.

• Start by adding a new exporter. For example, if your backend supports OTLP over HTTP, add the following:

  exporters:
    otlphttp/example:
      endpoint: <your-endpoint-url>
  

• Then override the exporters for telemetry pipelines that you want to use for your backend.

  service:
    pipelines:
      traces:
        exporters: [debug, otlp_grpc/jaeger, span_metrics, otlphttp/example]
  

Vendor backends might require you to add additional parameters for authentication, please check their documentation. Some backends require different exporters, you may find them and their documentation available at opentelemetry-collector-contrib/exporter.

After updating the otelcol-config-extras.yml, start the demo by running make start. After a while, you should see the traces flowing into your backend as well.