Skip to main content
This guide shows how to run the OpenTelemetry Collector locally using Docker Compose. You’ll:
  • create a minimal collector configuration that listens for OTLP (gRPC and HTTP),
  • write a docker-compose.yaml that mounts the config into the container and forwards host ports,
  • start the collector with docker compose up.
References:

​
1) Minimal collector configuration

Save the following as otel-collector-config.yaml. This config enables the OTLP receiver (gRPC and HTTP) and a debug exporter for traces, metrics, and logs.
Important: the collector listens on port 4317 for OTLP/gRPC and 4318 for OTLP/HTTP. When running in Docker, these container ports must be published to the host.

​
2) Choose an image

You can pick either the core or contrib image from Docker Hub:
  • Core: otel/opentelemetry-collector — a minimal set of components.
  • Contrib: otel/opentelemetry-collector-contrib — includes many additional receivers, exporters and processors.
Tip: pin a tag to lock a specific version, for example:

​
3) docker-compose.yaml

Create a docker-compose.yaml next to your otel-collector-config.yaml. This example:
  • uses the contrib image,
  • mounts the local config into the container at the collector’s default path,
  • exposes ports 4317 and 4318,
  • sets a readable container name.
Save as docker-compose.yaml:

​
Mount path and —config flag

If you mount the config file to a non-default path inside the container, pass the --config flag via the command: field in your compose file. In the example above we mount to /etc/otelcol/config.yaml, which is the collector’s default config path, so no command: is necessary.

​
4) Start the collector

From the directory containing both files:
You should see the collector start and state that its gRPC and HTTP listeners are ready. Example (truncated):

​
Quick reference

ItemDescriptionExample / Command
Config fileCollector config enabling OTLP receiver and debug exporterotel-collector-config.yaml (see above)
Collector imageChoose core or contrib from Docker Hubotel/opentelemetry-collector-contrib:0.135.0
PortsHost-to-container forwarding for OTLP4317:4317 (gRPC), 4318:4318 (HTTP)
Start commandBring container up with Composedocker compose up

​
Troubleshooting

If you see an error about a conflicting container name (for example: “Conflict. The container name “/otel-collector” is already in use…”), either remove or rename the existing container before reusing that name:
  • Remove: docker rm -f otel-collector
  • Or choose a different container_name in the compose file.
That’s it — your OpenTelemetry Collector is now running in Docker and ready to receive OTLP traffic on ports 4317 (gRPC) and 4318 (HTTP).

Watch Video

Practice Lab