> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Compose

> Implantando o ClickStack Open Source com Docker Compose - a pilha de observabilidade do ClickHouse

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

Todos os componentes do ClickStack Open Source são distribuídos separadamente como imagens Docker distintas:

* **ClickHouse**
* **HyperDX**
* **OpenTelemetry collector (OTel)**
* **MongoDB**

Essas imagens podem ser combinadas e implantadas localmente com o Docker Compose.

O Docker Compose expõe portas adicionais para observabilidade e ingestão com base na configuração padrão do `otel-collector`:

* `13133`: endpoint de verificação de integridade da extensão `health_check`
* `24225`: receiver do Fluentd para ingestão de logs
* `4317`: receiver OTLP gRPC (padrão para traces, logs e métricas)
* `4318`: receiver OTLP HTTP (alternativa ao gRPC)
* `8888`: endpoint de métricas do Prometheus para monitorar o próprio coletor

Essas portas permitem integrações com várias fontes de telemetria e deixam o OpenTelemetry collector pronto para produção para diferentes necessidades de ingestão.

<div id="suitable-for">
  ### Indicado para
</div>

* Testes locais
* Provas de conceito
* Implantações em produção em que a tolerância a falhas não é necessária e um único servidor é suficiente para hospedar todos os dados do ClickHouse
* Ao implantar o ClickStack, mas hospedar o ClickHouse separadamente, por exemplo, usando o ClickHouse Cloud

<div id="deployment-steps">
  ## Etapas de implantação
</div>

<br />

<Steps>
  <Step>
    ### Clone o repositório

    Para implantar com Docker Compose, clone o repositório do ClickStack, entre no diretório e execute `docker-compose up`:

    ```shell theme={null}
    git clone https://github.com/ClickHouse/ClickStack.git
    docker compose up
    ```
  </Step>

  <Step>
    ### Acesse a UI do HyperDX

    Acesse [http://localhost:8080](http://localhost:8080) para abrir a UI do HyperDX.

    Crie um usuário, informando um nome de usuário e uma senha que atendam aos requisitos.

    Ao clicar em `Create`, as fontes de dados serão criadas para a instância do ClickHouse implantada com Docker Compose.

    <Info>
      **Substituir a conexão padrão**

      Você pode substituir a conexão padrão da instância integrada do ClickHouse. Para mais detalhes, consulte ["Using ClickHouse Cloud"](#using-clickhouse-cloud).
    </Info>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/16jdCy1HTWZ9Bvmz/images/use-cases/observability/hyperdx-login.png?fit=max&auto=format&n=16jdCy1HTWZ9Bvmz&q=85&s=6584c04fd42475189e28a0827d14d0f6" alt="UI do HyperDX" size="lg" width="3600" height="1900" data-path="images/use-cases/observability/hyperdx-login.png" />

    Para ver um exemplo de uso de outra instância do ClickHouse, consulte ["Using ClickHouse Cloud"](#using-clickhouse-cloud).
  </Step>

  <Step>
    ### Preencha os detalhes da conexão

    Para se conectar à instância do ClickHouse implantada, basta clicar em **Create** e aceitar as configurações padrão.

    Se preferir se conectar ao seu próprio **cluster externo do ClickHouse**, por exemplo, o ClickHouse Cloud, você pode inserir manualmente suas credenciais de conexão.

    Se for solicitado que você crie uma source, mantenha todos os valores padrão e preencha o campo `Table` com o valor `otel_logs`. Todas as outras configurações devem ser detectadas automaticamente, permitindo que você clique em `Save New Source`.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/16jdCy1HTWZ9Bvmz/images/use-cases/observability/hyperdx-logs.png?fit=max&auto=format&n=16jdCy1HTWZ9Bvmz&q=85&s=32135e58b7ee1c4085b12b41ef2147ac" alt="Criar fonte de logs" size="md" width="1944" height="1572" data-path="images/use-cases/observability/hyperdx-logs.png" />
  </Step>
</Steps>

<div id="modifying-settings">
  ## Modificando as configurações do Compose
</div>

Você pode modificar as configurações da stack, como a versão em uso, por meio do arquivo de variáveis de ambiente:

```shell theme={null}
user@example-host clickstack % cat .env

# Usado pelo docker-compose.yml
IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
LOCAL_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-local
ALL_IN_ONE_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-otel-collector
CODE_VERSION=2.8.0
IMAGE_VERSION_SUB_TAG=.8.0
IMAGE_VERSION=2
IMAGE_NIGHTLY_TAG=2-nightly
IMAGE_LATEST_TAG=latest

# Configurar URLs de domínio
HYPERDX_API_PORT=8000 #opcional (não deve ser utilizada por outros serviços)
HYPERDX_APP_PORT=8080
HYPERDX_APP_URL=http://localhost
HYPERDX_LOG_LEVEL=debug
HYPERDX_OPAMP_PORT=4320

# Configuração Otel/Clickhouse
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default
```

<div id="configuring-collector">
  ### Configurando o OpenTelemetry collector
</div>

A configuração do OTel collector pode ser alterada, se necessário — consulte ["Modificando a configuração"](/pt-BR/clickstack/ingesting-data/collector#modifying-otel-collector-configuration).

<div id="using-clickhouse-cloud">
  ## Usando ClickHouse Cloud
</div>

Esta distribuição pode ser usada com o ClickHouse Cloud, mas difere do [Managed ClickStack](/pt-BR/clickstack/deployment/managed). Nesta configuração, você gerencia a UI do ClickStack por conta própria, enquanto usa o ClickHouse Cloud apenas para compute e armazenamento. A menos que você tenha um motivo específico para operar a UI de forma independente, recomendamos usar o Managed ClickStack, que inclui autenticação integrada e recursos Enterprise adicionais, além de eliminar a necessidade de gerenciar a UI do ClickStack por conta própria.

Você deve:

* Remover o serviço do ClickHouse do arquivo `docker-compose.yml`. Isso é opcional para testes, pois a instância implantada do ClickHouse será simplesmente ignorada, embora desperdice recursos locais. Se remover o serviço, certifique-se de também remover quaisquer referências a ele, como `depends_on`.

* Modificar o OTel collector para usar uma instância do ClickHouse Cloud, definindo as variáveis de ambiente `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` e `CLICKHOUSE_PASSWORD` no arquivo compose. Especificamente, adicione as variáveis de ambiente ao serviço do OTel collector:

  ```shell theme={null}
  otel-collector:
      image: ${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
      environment:
        CLICKHOUSE_ENDPOINT: '<CLICKHOUSE_ENDPOINT>' # endpoint HTTPS aqui
        CLICKHOUSE_USER: '<CLICKHOUSE_USER>'
        CLICKHOUSE_PASSWORD: '<CLICKHOUSE_PASSWORD>'
        HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: ${HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
        HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
        OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}'
      ports:
        - '13133:13133' # extensão health_check
        - '24225:24225' # receiver do Fluentd
        - '4317:4317' # receiver OTLP gRPC
        - '4318:4318' # receiver OTLP HTTP
        - '8888:8888' # extensão de métricas
      restart: always
      networks:
        - internal
  ```

  O `CLICKHOUSE_ENDPOINT` deve ser o endpoint HTTPS do ClickHouse Cloud, incluindo a porta `8443`, por exemplo: `https://mxl4k3ul6a.us-east-2.aws.clickhouse.com:8443`

* Ao se conectar à UI do HyperDX e criar uma conexão com o ClickHouse, use suas credenciais do Cloud.

<div id="schema-choice-map-vs-json">
  ## Escolha de esquema: Map vs JSON
</div>

O ClickStack armazena atributos como colunas `Map(LowCardinality(String), String)` por padrão. Esse é o esquema recomendado para cargas de trabalho de observabilidade. Em combinação com a [serialização de map em buckets](/pt-BR/reference/data-types/map#bucketed-map-serialization) e índices de texto nas chaves e nos valores do map, ele permite lookups seletivos sem a sobrecarga de ingestão por chave das subcolunas JSON dinâmicas.

Um esquema do tipo `JSON` está disponível em beta para avaliação em cargas de trabalho com um conjunto pequeno e estável de chaves de atributo. Ele **não é recomendado** como padrão. Consulte [Map vs tipo JSON](/pt-BR/clickstack/ingesting-data/schema/map-vs-json) para ver a comparação completa e as variáveis de ambiente necessárias para habilitar o suporte a JSON.