---
title: Quickstart for Docker on Elastic Cloud Hosted
description: Learn how to set up the {{agent}} and EDOT SDKs in a Docker environment with Elastic Cloud Hosted to collect host metrics, logs, and application traces using the Managed OTLP Endpoint.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7920/solutions/observability/get-started/opentelemetry/quickstart/ech/docker
products:
  - Elastic Agent
  - Elastic Cloud Hosted
  - Elastic Observability
applies_to:
  - Elastic Cloud Hosted: Generally available
---

# Quickstart for Docker on Elastic Cloud Hosted
Learn how to set up the Elastic Agent and EDOT SDKs in a Docker environment with Elastic Cloud Hosted (ECH) to collect host metrics, logs, and application traces. This quickstart uses the [Elastic Cloud Managed OTLP Endpoint](https://docs-v3-preview.elastic.dev/elastic/opentelemetry/tree/main/reference/managed-inputs/managed-otlp-endpoint) — the recommended ingestion path for ECH.

## Guided setup

Use the **Add data** screen in Elastic Observability to generate install commands that are already configured with the values you need.
1. Open Elastic Observability.
2. Go to **Add data**.
3. Select what you want to monitor.
4. Follow the instructions.


## Prerequisites

- An Elastic Cloud Hosted deployment running version 9.0 or later.
- [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) installed on the host.


## Manual installation

Follow these steps to deploy the Elastic Agent and EDOT SDKs in Docker with ECH.
<stepper>
  <step title="Create the config file">
    Create an `otel-collector-config.yml` file with your Elastic Agent configuration for the Elastic Cloud Managed OTLP Endpoint. Refer to the [configuration reference](https://docs-v3-preview.elastic.dev/elastic/elastic-agent/tree/main/reference/edot-collector/config/default-config-standalone).
  </step>

  <step title="Find your endpoint and create an API key">
    **Find your endpoint**
    1. Log in to the [Elastic Cloud Console](https://cloud.elastic.co/).
    2. From the home page, find your deployment in **Hosted deployments**, and select **Manage**.
    3. In the **Application endpoints, cluster and component IDs** section, select **Managed OTLP**.
    4. Copy the public endpoint value.
    **Create an API key**
    <dropdown title="Using Kibana">
      1. Go to **Stack Management** → **API keys**.
      2. Click **Create API key**, enter a name, and enable **Control security privileges**.
      3. In the role descriptors box, enter the following:
         ```json
         {
           "otlp_writer": {
             "applications": [
               {
                 "application": "apm",
                 "resources": ["*"],
                 "privileges": ["event:write"]
               }
             ]
           }
         }
         ```
      4. Click **Create API key** and copy the encoded value.
    </dropdown>

    <dropdown title="Using the Elasticsearch API">
      Use the [Create API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) API:
      ```json

      {
        "name": "otlp-writer",
        "role_descriptors": {
          "otlp_writer": {
            "applications": [
              {
                "application": "apm",
                "resources": ["*"],
                "privileges": ["event:write"]
              }
            ]
          }
        }
      }
      ```
      The `event:write` privilege for the `apm` application is the minimum required to send data through the Elastic Cloud Managed OTLP Endpoint.
    </dropdown>
  </step>

  <step title="Create the .env file">
    Create a `.env` file with the following content. Replace the placeholder values with your Elastic Cloud credentials:
    ```bash
    HOST_FILESYSTEM=/
    DOCKER_SOCK=/var/run/docker.sock
    ELASTIC_AGENT_OTEL=true
    COLLECTOR_CONTRIB_IMAGE=elastic/elastic-agent:9.5.1
    ELASTIC_API_KEY=<your_api_key_here>
    ELASTIC_OTLP_ENDPOINT=<your_motlp_endpoint_here>
    OTEL_COLLECTOR_CONFIG=/path/to/otel-collector-config.yml
    ```
  </step>

  <step title="Create the compose file">
    Create a `compose.yml` file with the following content:
    ```yaml
    services:
     otel-collector:
       image: ${COLLECTOR_CONTRIB_IMAGE}
       container_name: otel-collector
       deploy:
         resources:
           limits:
             memory: 1.5G
       restart: unless-stopped
       command: ["--config", "/etc/otelcol-config.yml" ]
       network_mode: host
       user: 0:0
       volumes:
         - ${HOST_FILESYSTEM}:/hostfs:ro
         - ${DOCKER_SOCK}:/var/run/docker.sock:ro
         - ${OTEL_COLLECTOR_CONFIG}:/etc/otelcol-config.yml
       environment:
         - HOST_FILESYSTEM
         - ELASTIC_AGENT_OTEL
         - ELASTIC_API_KEY
         - ELASTIC_OTLP_ENDPOINT
         - STORAGE_DIR=/usr/share/elastic-agent
    ```
  </step>

  <step title="Start the Collector">
    To start the Collector, run:
    ```bash
    docker compose up -d
    ```
  </step>

  <step title="(Optional) Instrument your applications">
    To collect telemetry from applications and use the Elastic Agent as a gateway, instrument your target applications following the setup instructions:
    - [Android](https://docs-v3-preview.elastic.dev/elastic/apm-agent-android/tree/main/reference/edot-android)
    - [.NET](https://docs-v3-preview.elastic.dev/elastic/elastic-otel-dotnet/tree/main/reference/edot-dotnet/setup)
    - [iOS](https://docs-v3-preview.elastic.dev/elastic/apm-agent-ios/tree/main/reference/edot-ios)
    - [Java](https://docs-v3-preview.elastic.dev/elastic/elastic-otel-java/tree/main/reference/edot-java/setup)
    - [Node.js](https://docs-v3-preview.elastic.dev/elastic/elastic-otel-node/tree/main/reference/edot-node/setup)
    - [PHP](https://docs-v3-preview.elastic.dev/elastic/elastic-otel-php/tree/main/reference/edot-php/setup)
    - [Python](https://docs-v3-preview.elastic.dev/elastic/elastic-otel-python/tree/main/reference/edot-python/setup)
    Configure your SDKs to send the data to the local Elastic Agent using OTLP/gRPC (`http://localhost:4317`) or OTLP/HTTP (`http://localhost:4318`).
    <tip>
      Enable Central Configuration to configure your EDOT SDKs from within Kibana. Refer to [EDOT SDKs Central Configuration](https://docs-v3-preview.elastic.dev/elastic/opentelemetry/tree/main/reference/central-configuration).
    </tip>
  </step>

  <step title="Install the content packs">
    Install the **[System OpenTelemetry Assets](https://docs-v3-preview.elastic.dev/elastic/integration-docs/tree/main/reference/system_otel)** integration and the **[Docker OpenTelemetry Assets](https://docs-v3-preview.elastic.dev/elastic/integration-docs/tree/main/reference/docker_otel)** integration in Kibana.
  </step>

  <step title="Explore your data">
    Go to Kibana and select **Dashboards** to explore your newly collected data.
  </step>
</stepper>


## Using the `elasticsearch` exporter

If you need to write telemetry directly to Elasticsearch — for example, for pipeline customizations not yet supported through Elastic Cloud Managed OTLP Endpoint — use the following `.env` and compose configuration instead.
Retrieve your Elasticsearch URL and your API key:
1. Retrieve the Elasticsearch URL for your Elastic Cloud deployment:
   1. Go to the [Elastic Cloud console](https://cloud.elastic.co/).
2. Next to your deployment, select **Manage**.
3. Under **Applications** next to **Elasticsearch**, select **Copy endpoint**.
2. Create an API Key following [these instructions](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7920/deploy-manage/api-keys/elasticsearch-api-keys).

Create a `.env` file with your Elasticsearch endpoint and credentials:
```bash
HOST_FILESYSTEM=/
DOCKER_SOCK=/var/run/docker.sock
ELASTIC_AGENT_OTEL=true
COLLECTOR_CONTRIB_IMAGE=elastic/elastic-agent:9.5.1
ELASTIC_API_KEY=<your_api_key_here>
ELASTIC_ENDPOINT=<your_elasticsearch_endpoint_here>
OTEL_COLLECTOR_CONFIG=/path/to/otel-collector-config.yml
```

Use the following compose file, which passes `ELASTIC_ENDPOINT` instead of `ELASTIC_OTLP_ENDPOINT`:
```yaml
services:
 otel-collector:
   image: ${COLLECTOR_CONTRIB_IMAGE}
   container_name: otel-collector
   deploy:
     resources:
       limits:
         memory: 1.5G
   restart: unless-stopped
   command: ["--config", "/etc/otelcol-config.yml" ]
   network_mode: host
   user: 0:0
   volumes:
     - ${HOST_FILESYSTEM}:/hostfs:ro
     - ${DOCKER_SOCK}:/var/run/docker.sock:ro
     - ${OTEL_COLLECTOR_CONFIG}:/etc/otelcol-config.yml
   environment:
     - HOST_FILESYSTEM
     - ELASTIC_AGENT_OTEL
     - ELASTIC_API_KEY
     - ELASTIC_ENDPOINT
     - STORAGE_DIR=/usr/share/elastic-agent
```


## Troubleshooting

The following issues might occur.

### API key prefix not found

The following error is due to an improperly formatted API key:
```txt
Exporting failed. Dropping data.
{"kind": "exporter", "data_type": }
"Unauthenticated desc = ApiKey prefix not found"
```

Format your API key as `"Authorization": "ApiKey <api-key-value-here>"` or `"Authorization=ApiKey <api-key>"` depending on whether you're using a Collector or SDK.
For additional troubleshooting, refer to [Troubleshooting common issues with the Elastic Agent](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7920/troubleshoot/ingest/opentelemetry/edot-collector) and [Troubleshooting the EDOT SDKs](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7920/troubleshoot/ingest/opentelemetry/edot-sdks).