Instalar com Docker

O DumbMonit roda como um único contêiner: o servidor dumbmonit (coleta, API, alertas, interface web) inicia seu próprio VictoriaMetrics para armazenar as séries temporais; o binário acompanha a imagem. A configuração e o estado ficam em um banco SQLite embutido. Um volume, /data, guarda o banco, o segredo da instância e as séries temporais.

Tags de imagem

ghcr.io/selfhostr/dumbmonit:latest é a última versão com tag (amd64; as imagens arm64 estão pausadas por enquanto); :edge acompanha o último commit de dev. Para rodar a partir do código-fonte, docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build compila a mesma imagem localmente (cerca de dez minutos na primeira vez; só o Docker é necessário).

Pré-requisitos

• Docker Engine com o plugin Compose (docker compose version funciona).
• Uma máquina que alcance os monitores que você quer monitorar. Ela não precisa ser alcançável por eles, exceto no caso dos agentes, que enviam suas medições ao servidor por HTTP.
• A porta 8080 livre no host, ou outra porta de sua escolha (veja abaixo).

O arquivo Compose

Este é o docker-compose.yml completo (nenhum arquivo .env necessário); salve-o em um diretório só dele:

services:
  dumbmonit:
    image: ghcr.io/selfhostr/dumbmonit:latest
    ports:
      - "8080:8080"
    volumes:
      - dumbmonit-data:/data
      # Or a host directory; on a SELinux host (Fedora, RHEL) add `:Z`:
      # - ./dumbmonit:/data:Z
    # environment:
    #   PUID: "1000"   # owner of the files in /data (default 65532)
    #   PGID: "1000"
    restart: unless-stopped
    stop_grace_period: 30s
    read_only: true
    tmpfs: [/tmp]
    # Starts as root only to give /data to user 65532 (or PUID/PGID), then
    # drops root for good: a host directory works as it is. Remove `user` and
    # `cap_add` to run as 65532 from the start (the files must belong to it).
    user: "0:0"
    cap_drop: [ALL]
    cap_add: [CHOWN, DAC_READ_SEARCH, SETUID, SETGID]
    security_opt: ["no-new-privileges:true"]
    sysctls:
      net.ipv4.ping_group_range: "0 2147483647"

volumes:
  dumbmonit-data:
    name: dumbmonit-data

Em seguida, inicie:

docker compose up -d

A imagem publicada é baixada; o sistema de arquivos somente leitura, as capabilities, PUID/PGID e o sysctl ping_group_range são explicados em Permissões e diretório de dados e Ping ICMP sem capability. As opções (porta, segredo, retenção, VictoriaMetrics externo, capturas de tela) são variáveis de ambiente que você mesmo adiciona.

Compilando a imagem você mesmo

A partir de um clone do repositório, docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build compila a mesma imagem localmente (cerca de dez minutos a frio; não é necessário Rust nem Node no host). Use isso para rodar a partir do código-fonte ou de um branch.

VictoriaMetrics embutido

A imagem contém o binário do VictoriaMetrics (/victoria-metrics-prod, de victoriametrics/victoria-metrics:v1.152.0). Quando DUMBMONIT_VM_URL não está definida, o servidor o inicia como processo filho escutando em 127.0.0.1:8428, armazena suas séries em /data/vm, encaminha suas linhas de log para o próprio log, o reinicia com backoff se ele morrer e o encerra no desligamento. Nada é publicado: a porta fica dentro do contêiner.

Duas variáveis merecem ser conhecidas: DUMBMONIT_VM_RETENTION (12 meses por padrão; 30d ou 2y também funcionam) e DUMBMONIT_VM_MEMORY (256MB, o orçamento de seus caches; aumente para centenas de hosts). O restante está na referência de configuração.

Para usar um VictoriaMetrics que você já executa, defina DUMBMONIT_VM_URL com o endereço dele (http://host:8428): o embutido então não é iniciado e /data/vm fica vazio.

Primeira inicialização

Abra https://<seu-host>:8080. O navegador mostra um aviso uma vez por causa do certificado autoassinado (veja HTTPS and encryption). Uma instância nova mostra a tela /setup, onde você cria a primeira conta de administrador (senha de pelo menos 12 caracteres).

A tela pede primeiro o código de configuração. Enquanto não existir administrador, o servidor imprime um código de uso único nos logs na inicialização:

docker compose logs dumbmonit | grep -A1 "setup code"

  First-run setup code: K7XQ4-M9PRT

Ele comprova que quem cria a conta de administrador controla o servidor, de modo que outra pessoa na rede não possa reivindicar uma instância nova primeiro. O código fica apenas na memória, muda a cada reinício até que exista um administrador, e as tentativas erradas têm limite de frequência. Para uma implantação automatizada, defina DUMBMONIT_SETUP_CODE para escolhê-lo você mesmo.

Depois adicione seu primeiro monitor: veja Adicione seu primeiro monitor.

Variáveis de ambiente

Tudo passa por variáveis de ambiente; nenhuma é obrigatória. Adicione as que precisar em environment: do serviço, como mostrado em Opções avançadas.

Variável	Padrão	Função
DUMBMONIT_BIND	0.0.0.0:8080	Endereço de escuta dentro do contêiner.
PUID / PGID	65532	Com user: "0:0": usuário e grupo com que o servidor roda, e dono dos arquivos em /data (detalhes). DUMBMONIT_PUID / DUMBMONIT_PGID também funcionam.
DUMBMONIT_DATA_DIR	/data	Banco SQLite (dumbmonit.db), segredo da instância (secret.key) e os dados do VictoriaMetrics embutido (vm/).
DUMBMONIT_VM_URL	(não definida)	URL de um VictoriaMetrics externo. Quando definida, o embutido não é iniciado.
DUMBMONIT_VM_RETENTION	12	Retenção do VictoriaMetrics embutido: meses, ou 30d, 2y.
DUMBMONIT_VM_MEMORY	256MB	Orçamento de memória dos caches do VictoriaMetrics embutido.
DUMBMONIT_VM_LISTEN	127.0.0.1:8428	Endereço de escuta do VictoriaMetrics embutido, dentro do contêiner.
DUMBMONIT_SECRET	(gerado)	Segredo da instância que criptografa credenciais de monitores e tokens.
DUMBMONIT_MAX_CONCURRENT_PROBES	64	Sondagens simultâneas, todos os coletores somados.
DUMBMONIT_PROBE_TIMEOUT_SECS	10	Duração máxima de uma sondagem.
DUMBMONIT_FLUSH_INTERVAL_SECS	5	Período de gravação para o VictoriaMetrics.
DUMBMONIT_LOG	info	Filtro de log (sintaxe do tracing, p. ex. debug, dumbmonit=trace).
DUMBMONIT_AGENT_DIR	/agents	Binários dos agentes servidos em /download/….
DUMBMONIT_RESET_PASSWORD	(vazia)	Defina como 1 para apagar a senha e todas as sessões na inicialização.
DUMBMONIT_SETUP_CODE	(gerado)	Código de configuração pedido por /setup enquanto não existir administrador. Se não definido, um código aleatório é impresso nos logs a cada inicialização.
DUMBMONIT_COOKIE_SECURE	(desligado)	Defina como 1 atrás de um proxy reverso TLS para marcar o cookie de sessão como Secure.
DUMBMONIT_ALERT_INTERVAL_SECS	30	Período de avaliação dos alertas (nunca abaixo de 10).
DUMBMONIT_ALERT_HISTORY_DAYS	90 dias	Retenção do histórico de alertas. Veja a referência de configuração para uma ressalva sobre sua unidade.
DUMBMONIT_BACKUP_ENABLED	ligado	Backups locais agendados do banco em /data/backups/. DUMBMONIT_BACKUP_DIR, _INTERVAL_HOURS (24) e _KEEP (7) os ajustam; veja Backup e restauração.

A lista completa, com detalhes, está na referência de configuração. Os nomes EZYMONIT_* anteriores à renomeação ainda são lidos como alternativa; veja Atualização.

Faça backup da chave secreta

Comunidades SNMP, senhas e tokens de API são criptografados com AES-256-GCM usando uma chave derivada do segredo da instância. Na primeira inicialização, o DumbMonit gera esse segredo em /data/secret.key (dentro do volume dumbmonit-data).

Faça backup de secret.key junto com o banco de dados

Sem ela, as credenciais dos monitores são irrecuperáveis: um banco restaurado sozinho resulta em uma instância que não consegue falar com nada. O servidor detecta uma chave ausente ou alterada na inicialização e se recusa a continuar com uma mensagem explícita, em vez de falhar silenciosamente a cada sondagem. Os backups agendados a copiam para você — veja Backup e restauração.

Se preferir ser dono do segredo, defina DUMBMONIT_SECRET no arquivo Compose (exemplo) (32 caracteres aleatórios ou mais). Guarde-o no seu gerenciador de senhas.

Atualização

docker compose pull
docker compose up -d

As migrações do banco rodam na inicialização. Os dados do VictoriaMetrics não são tocados.

Faça um backup antes

Settings → Backup → Back up now grava em poucos segundos uma cópia consistente do banco e de secret.key em /data/backups/, e é a partir dela que você restaura se a atualização der errado. Veja Backup e restauração.

Bind mounts

Um docker-compose.yml existente continua funcionando como está: a imagem continua rodando com o usuário 65532. O arquivo novo acrescenta user: "0:0" e uma linha cap_add para que um diretório do host funcione sem preparação (Permissões); copie essas duas linhas se quiser passar a um bind mount.

A partir do EzyMonit e da configuração com dois contêineres

O DumbMonit se chamava EzyMonit até setembro de 2026, e rodava como dois contêineres, o servidor e um serviço victoriametrics separado. A atualização exige mover uma vez os dados do projeto antigo para o novo volume. O projeto antigo se chamava ezymonit (seus volumes ezymonit_ezymonit-data e ezymonit_vm-data; docker volume ls confirma). A partir do diretório antigo:

docker compose down

Depois, com o novo docker-compose.yml:

docker volume create dumbmonit-data
docker run --rm -v ezymonit_ezymonit-data:/from -v dumbmonit-data:/to alpine cp -a /from/. /to/
docker run --rm -v ezymonit_vm-data:/from -v dumbmonit-data:/to alpine sh -c 'mkdir -p /to/vm && cp -a /from/. /to/vm/'
docker compose up -d

O diretório de dados do VictoriaMetrics antigo tem a estrutura que o embutido usa: nada a converter. A alternativa é manter o VictoriaMetrics externo e apontar DUMBMONIT_VM_URL para ele.

O que o servidor resolve sozinho na primeira inicialização:

• As variáveis EZYMONIT_* ainda são lidas como alternativa, com um aviso na inicialização por variável (EZYMONIT_X is deprecated, use DUMBMONIT_X).
• /data/ezymonit.db é renomeado para dumbmonit.db.
• Os tokens de agente ezym_… continuam funcionando; os novos são dmon_…. Os agentes continuam enviando dados; execute novamente o comando de instalação em cada máquina quando for conveniente, ele migra o serviço antigo no lugar.
• O cookie de sessão mudou de nome: todos entram de novo uma vez. A preferência de tema do navegador é mantida.

O que ele não resolve: o prefixo das métricas mudou de ezymonit_ para dumbmonit_ sem compatibilidade. As séries antigas permanecem no VictoriaMetrics com o nome antigo e expiram conforme a retenção; os gráficos e as regras integradas recomeçam a partir da atualização. Regras de alerta personalizadas que citam métricas ezymonit_… precisam ser editadas.

Backup e restauração

Um volume nomeado, dumbmonit-data, guarda tudo:

Caminho	Conteúdo
dumbmonit.db	Monitores, regras, canais, estado dos alertas, sessões.
secret.key	O segredo da instância.
backups/	Os backups locais agendados: uma cópia do banco e do segredo, diária por padrão, sete mantidas.
vm/	Séries temporais do VictoriaMetrics (12 meses de retenção por padrão).

O DumbMonit faz backup do próprio banco em um agendamento, e exporta toda a configuração — monitores, credenciais, regras, canais — como um único arquivo criptografado com uma senha que você escolhe, que pode ser restaurado em uma instância nova. Ambos estão em Backup e restauração, junto com o que fazer antes de uma atualização e a única regra sobre secret.key que vale a pena ler duas vezes.

Para arquivar o próprio volume, gráficos incluídos, pare a stack e compacte-o com tar:

docker compose stop
docker run --rm -v dumbmonit-data:/data -v "$PWD:/backup" alpine \
  tar czf /backup/dumbmonit-data.tgz -C /data .
docker compose start

Para restaurar, crie o volume, extraia o arquivo nele da mesma forma e depois docker compose up -d.

Se o espaço for importante, --exclude=./vm mantém o arquivo pequeno: o banco e o segredo são a configuração, vm/ são apenas os gráficos.

Opções avançadas

O arquivo Compose acima não tem variáveis de propósito. Para mudar uma configuração, adicione um bloco environment: (ou uma linha nele) sob dumbmonit: no seu docker-compose.yml e execute docker compose up -d de novo. O contêiner é recriado; o volume de dados é mantido.

Outra porta. Mude o lado esquerdo do mapeamento; o contêiner continua escutando na 8080:

    ports:
      - "8099:8080"

Seu próprio segredo, em vez do gerado em /data/secret.key. Ele criptografa as credenciais dos monitores: perdê-lo significa digitar todas de novo.

    environment:
      DUMBMONIT_SECRET: replace-me-with-32-random-characters

Retenção e memória do VictoriaMetrics embutido (meses, ou 30d / 2y; um homelab de algumas dezenas de monitores cabe em 256 MB):

    environment:
      DUMBMONIT_VM_RETENTION: "24"
      DUMBMONIT_VM_MEMORY: 512MB

VictoriaMetrics externo; o embutido então não é iniciado:

    environment:
      DUMBMONIT_VM_URL: http://victoriametrics:8428

Senha perdida. Adicione a linha abaixo, execute docker compose up -d, crie o primeiro administrador de novo na interface (monitores, regras e canais permanecem), depois remova a linha e execute docker compose up -d mais uma vez:

    environment:
      DUMBMONIT_RESET_PASSWORD: "1"

Capturas de tela das mudanças de sites: um Chromium sem interface ao lado do servidor; veja abaixo Capturas de tela das mudanças de sites.

Mais variáveis: referência de configuração.

Capturas de tela das mudanças de sites

O monitor de mudanças de sites sempre compara o texto visível das páginas. Guardar uma captura de tela de cada nova versão exige um navegador, e a imagem do DumbMonit não traz nenhum: um Chromium sem interface roda como segundo serviço, e DUMBMONIT_BROWSER_URL diz ao servidor onde encontrá-lo.

Adicione estas linhas ao seu docker-compose.yml e execute depois docker compose up -d:

services:
  dumbmonit:
    environment:
      DUMBMONIT_BROWSER_URL: http://browser:9222
  browser:
    image: chromedp/headless-shell:stable
    shm_size: 256m
    restart: unless-stopped

• browser é o nome do serviço; na rede do Compose, http://browser:9222 leva até ele. Nada publica a sua porta: só o DumbMonit fala com ele.
• shm_size: 256m: o Chromium renderiza em /dev/shm, e os 64 MB padrão do Docker são pouco para uma página longa.
• Serve qualquer Chromium iniciado com --remote-debugging-port; aqui se usa a imagem chromedp/headless-shell.

Sem navegador, todo o resto funciona como de costume (comparação de texto, alertas, cópias antes/depois); os instantâneos apenas não têm imagem. Enquanto o servidor não alcançar um navegador, o formulário de um monitor de mudanças de sites mostra um aviso com estas linhas. Se o aviso permanecer após a reinicialização, verifique docker compose logs browser, se o nome do host em DUMBMONIT_BROWSER_URL é o nome do serviço e se os dois serviços estão no mesmo projeto Compose.

Proxy reverso

A interface e a API são servidas em uma única porta, que só fala HTTPS (uma requisição HTTP simples recebe um redirecionamento, veja HTTPS and encryption). Um proxy reverso precisa, portanto, se conectar ao contêiner por HTTPS (https://dumbmonit:8080), com a verificação de certificado desativada para esse trecho ou com o certificado do DumbMonit confiável. Nenhum WebSocket é usado: a interface consulta a API periodicamente, então qualquer proxy reverso funciona sem configuração especial.

monit.example.com {
    reverse_proxy https://127.0.0.1:8080 {
        transport http {
            tls_insecure_skip_verify
        }
    }
}

server {
    listen 443 ssl;
    server_name monit.example.com;
    # ssl_certificate / ssl_certificate_key …

    location / {
        proxy_pass https://127.0.0.1:8080;
        proxy_ssl_verify off;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Os agentes enviam lotes de recuperação após uma queda:
        client_max_body_size 16m;
    }
}

Quando o proxy termina o TLS, defina DUMBMONIT_COOKIE_SECURE: "1" para que o cookie de sessão seja enviado apenas por HTTPS. Defina-o somente se todos os navegadores acessarem o DumbMonit por HTTPS: o navegador nunca devolveria o cookie e o login seria impossível.

Agentes atrás de um proxy

O comando de instalação exibido ao criar um token de agente usa a URL que o seu navegador usou para acessar a interface. Se for a URL do proxy, os agentes também a usarão: garanta que /install.sh, /install.ps1, /download/… e /api/ingest passem pelo proxy.

Permissões e diretório de dados

O servidor nunca roda como root. Por padrão, a imagem roda com o usuário 65532:65532, a quem um volume nomeado criado pelo Docker já pertence.

Um bind mount (./dumbmonit:/data), ao contrário, mantém o dono do diretório do host, muitas vezes root quando foi o Docker que o criou. É por isso que o arquivo Compose acima inicia o contêiner como root (user: "0:0"). O servidor só fica root por um instante: antes de abrir o banco de dados, iniciar o VictoriaMetrics ou escutar na rede, entrega /data a 65532:65532 (só as entradas que pertencem a outra pessoa, sem seguir links simbólicos), abandona o root de vez e verifica que não consegue recuperá-lo. As quatro capabilities de cap_add servem só para esse passo; nenhuma sobra depois. no-new-privileges e o sistema de arquivos raiz somente leitura continuam ativos: /data e /tmp são os únicos caminhos graváveis.

Escolher o dono: PUID e PGID. Com user: "0:0", indique o uid e o gid com que o servidor roda; os arquivos são entregues a eles na inicialização:

    environment:
      PUID: "1000"
      PGID: "1000"

DUMBMONIT_PUID / DUMBMONIT_PGID também funcionam e têm prioridade. O 0 é recusado. No Unraid, PUID=99 e PGID=100 correspondem ao dono habitual de appdata. Sem user: "0:0", PUID/PGID são ignorados.

Sem user: "0:0" (um simples docker run -v ./data:/data, ou --user 1000:1000), nenhum dono muda e /data já precisa ser gravável. Se não for, o servidor para e sugere primeiro --user 0:0, depois sudo chown -R 65532:65532 ./data no host para um bind mount ou, para um volume nomeado:

docker run --rm -v dumbmonit-data:/data alpine chown -R 65532:65532 /data

SELinux e Podman

Em um host onde o SELinux está em modo enforcing (Fedora, RHEL, CentOS Stream, AlmaLinux…), um bind mount é negado ao contêiner, inclusive ao root, enquanto não tiver um rótulo de contêiner. Adicione :Z ao volume, ou :z se outros contêineres compartilham o diretório:

    volumes:
      - ./dumbmonit:/data:Z

Sem isso, o servidor para com the host enforces SELinux and the volume has no container label. Os volumes nomeados são rotulados pelo Docker e não precisam de nada.

O Podman rootless funciona do mesmo jeito, com --user 0:0. O root no contêiner é o seu próprio usuário no host, e os arquivos de um bind mount vão para o uid 65532 do contêiner, que o host mostra como um dos seus sub-uids (165531 com o /etc/subuid habitual). Leia-os com podman unshare ls -l ./dumbmonit. Para mantê-los sob o seu próprio uid, rode o contêiner como você mesmo; nenhum dono muda então:

podman run --userns keep-id --user "$(id -u):$(id -g)" -v ./dumbmonit:/data:Z …

Ping ICMP sem capability

O monitor de ping envia ecos ICMP. Em vez de um socket raw — que exige NET_RAW, e uma capability concedida a um usuário não root do contêiner não é utilizável de qualquer forma — ele usa um socket ICMP echo, que o Linux permite aos grupos listados em net.ipv4.ping_group_range. O arquivo Compose define esse sysctl dentro do namespace de rede do próprio contêiner:

services:
  dumbmonit:
    sysctls:
      net.ipv4.ping_group_range: "0 2147483647"

Nada muda no host. O Docker 20.10 e posteriores definem essa faixa em todo contêiner por conta própria; as linhas explícitas garantem que ela valha em engines mais antigos e no Podman. Sem ela, a verificação informa um erro de configuração (exibido no monitor, sem notificação), nunca um falso “host fora do ar”. Com docker run, passe --sysctl net.ipv4.ping_group_range="0 2147483647". Enquanto o servidor não conseguir abrir um socket ICMP, o formulário de um monitor de ping mostra um aviso com estas linhas.

Testando sem hardware

Adicione um monitor de demonstração: ele produz medições falsas sem nada a preparar, de modo que gráficos, regras e notificações podem ser testados imediatamente. Para dados SNMP reais, a máquina que executa o Docker muitas vezes basta — instale o snmpd nela (apt install snmpd, permita a comunidade public na bridge do Docker em /etc/snmp/snmpd.conf) e adicione um dispositivo SNMP com o endereço do host nessa bridge (172.17.0.1 por padrão): o perfil é detectado automaticamente e interfaces, memória e processos aparecem.

Desenvolvedores podem adicionar o overlay docker-compose.dev.yml para publicar o VictoriaMetrics embutido em :8428 do host, para consultas MetricsQL diretas:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d