ULC Lab · implementação reproduzível

Laboratório: EspoCRM escalável e monitorado em Docker Compose com Prometheus e Grafana

Você terá um ambiente EspoCRM funcional, escalável com Docker Compose, monitorado por Prometheus e Grafana, acessível em rede privada. O laboratório leva cerca de 2 horas.

Ligado ao treinamento Escalando e protegendo CRMs de código aberto em nuvem privada

ULC-LAB-CRM-0002 · Status de validaçãoNão validado pela Upnetix: roteiro derivado da documentação oficial, para você executar e validar

Duração estimada: 120 min
Passos: 13
Validações: 5
Versões da documentação consultada: EspoCRM a versão estável atual · MariaDB a versão estável atual · Docker a versão estável atual · Docker Compose a versão estável atual · Prometheus a versão estável atual · Grafana a versão estável atual

Objetivo

Demonstrar como implantar o EspoCRM em containers Docker, com banco de dados MariaDB dedicado, expor métricas via Prometheus e visualizar dados operacionais no Grafana. O foco é praticar a escalabilidade, monitoramento e princípios básicos de segurança em nuvem privada, usando apenas software livre.

Topologia

Três máquinas virtuais (ou hosts): uma para EspoCRM (com Docker Compose), uma para Prometheus e Grafana, e uma para acesso administrativo. EspoCRM expõe a porta 8080, MariaDB fica isolado na rede Docker, Prometheus coleta métricas do container EspoCRM e do próprio host. Grafana acessa Prometheus via HTTP. Endereços de exemplo: EspoCRM 192.168.56.10, Prometheus/Grafana 192.168.56.20, admin 192.168.56.30.

        +-------------------+
        |   Admin (CLI)    |
        | 192.168.56.30    |
        +--------+---------+
                 |
                 |
+----------------+----------------+
|                                 |
|    Rede Privada 192.168.56.0    |
|                                 |
+----------------+----------------+
                 |
        +--------+---------+
        |   EspoCRM VM     |
        | 192.168.56.10    |
        +--------+---------+
                 |
        +--------+---------+
        | Prometheus/Grafana|
        | 192.168.56.20    |
        +------------------+

Equipamentos e software

Item	Requisito, licença ou versão
VM EspoCRM	1 vCPU, 2GB RAM, 10GB disco, Ubuntu 22.04 ou superior
VM Prometheus/Grafana	1 vCPU, 2GB RAM, 10GB disco, Ubuntu 22.04 ou superior
VM Admin	1 vCPU, 1GB RAM, SSH client
EspoCRM	GPLv3 · a versão estável atual
MariaDB	GPLv2 · a versão estável atual
Docker	Apache 2.0 · a versão estável atual
Docker Compose	Apache 2.0 · a versão estável atual
Prometheus	Apache 2.0 · a versão estável atual
Grafana	AGPLv3 · a versão estável atual

Roteiro

Preparar as VMs e rede privada
Crie três VMs Ubuntu 22.04 em rede privada (ex: VirtualBox NAT Network ou bridge). Teste conectividade entre elas via ping.
```
ping 192.168.56.10
```
O que você deve ver: Respostas de ping entre todas as VMs.
Instalar Docker e Docker Compose na VM EspoCRM
Docker facilita o isolamento e escalabilidade. Siga a documentação oficial para instalar Docker e Compose.
```
sudo apt update && sudo apt install docker.io docker-compose -y
```
O que você deve ver: Docker e docker-compose instalados, 'docker --version' retorna versão.
Criar diretório do projeto e arquivo docker-compose.yml
Organize os serviços EspoCRM e MariaDB em containers. Compose simplifica o gerenciamento.
```
mkdir ~/espo-lab && cd ~/espo-lab && nano docker-compose.yml
```
O que você deve ver: Arquivo docker-compose.yml salvo.

Configurar docker-compose.yml para EspoCRM e MariaDB

Defina os serviços, volumes e variáveis de ambiente. MariaDB não deve expor porta para fora do Docker.

Exemplo de docker-compose.yml:

version: '3.7'
services:
  db:
    image: mariadb:latest
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: esporoot
      MYSQL_DATABASE: espocrm
      MYSQL_USER: espouser
      MYSQL_PASSWORD: espopass
    volumes:
      - db_data:/var/lib/mysql
  espo:
    image: espocrm/espocrm:latest
    depends_on:
      - db
    ports:
      - "8080:80"
    environment:
      - DB_HOST=db
      - DB_NAME=espocrm
      - DB_USER=espouser
      - DB_PASSWORD=espopass
    volumes:
      - espo_data:/var/www/html
volumes:
  db_data:
  espo_data:

O que você deve ver: Arquivo docker-compose.yml pronto para uso.

Subir os containers EspoCRM e MariaDB
Inicie os serviços. Compose orquestra os containers e volumes.
```
docker-compose up -d
```
O que você deve ver: Containers 'espo' e 'db' em execução, verificados com 'docker ps'.
Acessar EspoCRM pela web
Abra http://192.168.56.10:8080 no navegador da VM Admin. Complete o setup inicial do EspoCRM.
O que você deve ver: Tela de instalação do EspoCRM, depois dashboard ao finalizar setup.
Instalar Prometheus e Grafana na VM 192.168.56.20
Prometheus coleta métricas, Grafana visualiza. Instale ambos conforme documentação oficial.
```
sudo apt update && sudo apt install prometheus grafana -y
```
O que você deve ver: Serviços prometheus e grafana-server ativos ('systemctl status').
Configurar Prometheus para coletar métricas do Docker
Prometheus pode capturar métricas do Docker via endpoint do cAdvisor. Instale cAdvisor na VM EspoCRM.
```
docker run -d --name=cadvisor -p 8081:8080 --volume=/:/rootfs:ro --volume=/var/run:/var/run:ro --volume=/sys:/sys:ro --volume=/var/lib/docker/:/var/lib/docker:ro gcr.io/cadvisor/cadvisor:latest
```
O que você deve ver: cAdvisor rodando em http://192.168.56.10:8081/metrics.
Editar prometheus.yml para adicionar target do cAdvisor
Prometheus precisa saber onde buscar métricas. Edite /etc/prometheus/prometheus.yml.
```
Exemplo de scrape_configs:
scrape_configs:
  - job_name: 'cadvisor'
    static_configs:
      - targets: ['192.168.56.10:8081']
```
O que você deve ver: Arquivo prometheus.yml salvo com novo target.
Reiniciar Prometheus e validar coleta
Reinicie Prometheus para aplicar a configuração.
```
sudo systemctl restart prometheus
```
O que você deve ver: No Prometheus web UI (http://192.168.56.20:9090), target 'cadvisor' aparece UP em Status > Targets.
Configurar Grafana para acessar Prometheus
Grafana precisa de um data source Prometheus. Acesse http://192.168.56.20:3000 (admin/admin), adicione Prometheus em Configuration > Data Sources.
O que você deve ver: Prometheus listado como data source OK no Grafana.
Importar dashboard Docker no Grafana
Use um dashboard pronto para visualizar métricas dos containers.
```
No Grafana, Import > ID 893 (Docker and system monitoring)
```
O que você deve ver: Dashboard com gráficos de uso de CPU, memória e containers do EspoCRM.
Escalar EspoCRM para dois containers
Teste a escalabilidade subindo mais uma instância do EspoCRM. Compose facilita isso.
```
docker-compose up -d --scale espo=2
```
O que você deve ver: Dois containers 'espo' rodando, visíveis em 'docker ps' e no dashboard Grafana.

Como saber que funcionou

Teste	Comando	Critério
Acessar EspoCRM via navegador	`http://192.168.56.10:8080`	Dashboard do EspoCRM carrega e é utilizável.
Verificar containers ativos	`docker ps`	Containers 'espo' e 'db' (e 'cadvisor') em status 'Up'.
Verificar coleta de métricas no Prometheus	`Acessar http://192.168.56.20:9090/targets`	'cadvisor' aparece como UP.
Visualizar métricas no Grafana	`Acessar http://192.168.56.20:3000`	Gráficos mostram atividade dos containers EspoCRM.
Escalar containers EspoCRM	`docker-compose up -d --scale espo=2 && docker ps`	Dois containers 'espo' ativos simultaneamente.

Troubleshooting

Sintoma	Causa provável	Correção
EspoCRM não abre no navegador	Porta 8080 bloqueada ou container não está rodando	Verifique firewall e status do container com 'docker ps'.
Prometheus não coleta métricas do cAdvisor	Target incorreto ou cAdvisor não está acessível na rede	Confirme IP e porta do cAdvisor e conectividade entre as VMs.
Grafana não conecta ao Prometheus	Data source mal configurado ou Prometheus offline	Revise URL do Prometheus e status do serviço.
Erro de permissão em volumes Docker	Usuário do host sem permissão nos volumes	Ajuste permissões dos diretórios ou execute com 'sudo'.
Escalando EspoCRM, só um container responde	Falta de balanceador de carga	Para produção, adicione um proxy reverso como Nginx ou Traefik.

Segurança e hardening

Altere as senhas padrão do MariaDB imediatamente após o laboratório
Restrinja o acesso à porta 8080 apenas à rede privada
Não exponha cAdvisor para a internet pública
Atualize as imagens Docker regularmente
Consulte a documentação do EspoCRM para hardening adicional

Checklist final

VMs em rede privada e com conectividade
Docker e Compose instalados e testados
EspoCRM e MariaDB rodando em containers
Acesso ao EspoCRM via navegador
Prometheus coletando métricas do cAdvisor
Grafana mostrando dashboards do EspoCRM
Escalabilidade testada com múltiplos containers EspoCRM

Referências

Documentação oficial do EspoCRM · EspoCRM (docs.espocrm.com)
Documentação Docker Compose · Docker, Inc. (docs.docker.com)
Documentação Prometheus · Prometheus (CNCF) (prometheus.io)
Documentação Grafana · Grafana Labs (grafana.com)

Verificação editorial

Publicado: 09/09/2026
Última revisão: 09/09/2026
Versão do conteúdo: 1.0
Referências: 4 oficiais
Revisão técnica: redação e revisão por IA, URLs conferidas na publicação
Status: Atual

Encontrou um erro? Escreva para comercial@upnetix.com.br com o endereço da página. A revisão semestral por IA nunca altera comandos ou configurações sem passar pela fila de revisão.