Hospedar Umami em um VPS gerenciado: suas estatísticas web em seu servidor

O que o Umami faz

O Umami é uma plataforma de código aberto de estatísticas web e de produto. A documentação dele descreve uma ferramenta que reúne o tráfego, as campanhas, o comportamento dos visitantes, as conversões, a retenção e a receita, da primeira visita aos resultados que contam para sua atividade. Ele é escrito em TypeScript sobre Next.js, e a imagem Docker dele roda em uma conta sem privilégios.

• A aquisição: páginas vistas, visitantes, origens, países, dispositivos e atividade em tempo real, com campanhas UTM, links curtos e pixels de rastreamento.
• O comportamento: eventos personalizados, jornadas, gravações de sessão, mapas de calor, segmentos, coortes e retenção.
• A conversão: metas, funis, atribuição e acompanhamento da receita por página e por campanha.
• O compartilhamento: painéis, equipes, uma URL de compartilhamento pública, uma API e um servidor MCP somente leitura para seu assistente de IA.
• Os sites modernos: o FAQ indica que o Umami acompanha sozinho a navegação entre páginas nas aplicações de página única, sem configuração extra.

Uma instância acompanha vários sites: cada um recebe o próprio identificador e o próprio script de rastreamento, e seus colegas se organizam por contas e equipes.

O que a licença MIT permite

O Umami é publicado sob a licença MIT, em nome da Umami Software, Inc. Ela concede gratuitamente o direito de usar, copiar, modificar, fundir, publicar, distribuir, sublicenciar e vender cópias do software. Você pode, portanto, rodá-lo para sua empresa e para os sites de seus clientes, sem licença a comprar.

A única condição dela: o aviso de copyright e o aviso de permissão acompanham todas as cópias ou partes substanciais do software. Como toda licença MIT, ela fornece o software “no estado em que se encontra”, sem garantia.

Cookies e dados pessoais: o que o projeto diz

A documentação apresenta o Umami como uma medição de audiência sem cookies, sem rastreamento entre sites e sem coleta automática de dados pessoais. Auto-hospedado, ele mantém suas estatísticas em seu próprio servidor: você decide onde elas ficam e por quanto tempo.

Três configurações do script de rastreamento vão mais longe, se você quiser: data-exclude-search retira os parâmetros de busca das URLs registradas, data-exclude-hash retira o fragmento, e data-do-not-track desativa o rastreamento nos navegadores que expõem a preferência Do Not Track. A documentação observa que essa última configuração não é, por si só, uma solução completa de gestão do consentimento.

Se você identificar os visitantes conectados com data-distinct-id ou umami.identify(), a documentação recomenda um identificador de usuário interno ou um hash em vez de um endereço de e-mail: o valor pode ser lido no HTML da página.

A instalação com Docker Compose e PostgreSQL

O repositório fornece um docker-compose.yml que inicia o Umami e o banco PostgreSQL dele. Desde a versão 3, o PostgreSQL é o único banco suportado, na versão 12.14 no mínimo, e a documentação recomenda configurá-lo no fuso horário UTC. Em um servidor com o Docker instalado, crie uma pasta e comece pelos segredos, gerados ao acaso com openssl, como sugere a documentação:

cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
APP_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

Coloque então este compose.yaml ao lado. Ele retoma o arquivo do projeto na versão 3.4.1, com duas mudanças: os segredos vêm do arquivo .env, e a porta é publicada apenas em 127.0.0.1.

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

docker compose up -d
curl -s http://127.0.0.1:3000/api/heartbeat

• DATABASE_URL: a única variável obrigatória, a cadeia de conexão com o banco. A senha hexadecimal entra como está; uma senha com caracteres especiais exigiria a codificação por cento.
• APP_SECRET: uma cadeia aleatória que protege os tokens de autenticação, exclusiva de cada instalação. No código da versão 3.4.1, ela também entra no cálculo dos identificadores de sessão: mantenha-a estável.
• TWO_FACTOR_ENCRYPTION_KEY: 64 caracteres hexadecimais que criptografam os segredos da autenticação em duas etapas. Sem ela, ninguém consegue ativar a autenticação em duas etapas.
• Na inicialização, o contêiner verifica a conexão e a versão do banco e aplica ele mesmo as migrações do esquema. Na primeira execução, ele cria as tabelas e a conta admin. A sonda /api/heartbeat responde {"ok":true} assim que o Umami está pronto.
• A tag latest acompanha a última versão publicada. O registro do projeto também publica tags de versão, como 3.4.1, para fixar a que você roda.

A documentação de instalação não informa números de memória nem de processador. O tamanho depende do tráfego dos sites acompanhados e do volume de dados que você guarda. Em um VPS gerenciado, descreva-nos o uso e recomendamos o tamanho adequado.

HTTPS: o proxy reverso

O Umami escuta em HTTP na porta 3000, e a documentação sugere servi-lo atrás de seu servidor web, por um proxy reverso. Dê a ele um subdomínio próprio, como stats.example.com, apontado para o servidor com registros A e AAAA. Servir o Umami em um caminho passa por BASE_PATH, uma variável lida na compilação da aplicação: com a imagem publicada, o subdomínio é o caminho direto.

O proxy também precisa repassar o endereço do visitante. O Umami o lê nos cabeçalhos que recebe, entre eles X-Real-IP e X-Forwarded-For: ele o usa para distinguir os visitantes e localizar o país deles. Se seu proxy usa outro cabeçalho, CLIENT_IP_HEADER o nomeia.

Com o Caddy

O Caddy obtém o certificado Let's Encrypt e ativa o HTTPS sozinho. A diretiva reverse_proxy dele define X-Forwarded-For por padrão: estas três linhas bastam.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Com o Nginx e o Certbot

Este bloco retoma o exemplo de Nginx da documentação do Umami, na porta 80 para deixar o Certbot instalar o HTTPS:

server {
  listen 80;
  listen [::]:80;
  server_name stats.example.com;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Em seguida, o Certbot instala o certificado e cuida de renová-lo:

sudo certbot --nginx

O primeiro login: a conta admin e a autenticação em duas etapas

Ao criar o banco, o Umami abre uma conta de administrador: usuário admin, senha umami. A documentação pede para mudar essa senha no primeiro login.

1. Abra seu endereço HTTPS e conecte-se com admin e umami.
2. Abra Settings a partir do botão de perfil da barra lateral, depois Profile, e clique em Change password.
3. Na aba Security, ative a autenticação em duas etapas: escaneie o QR code com seu aplicativo autenticador, informe o código de seis dígitos e guarde em lugar seguro os dez códigos de backup, que só são exibidos uma vez.

• Exigir a autenticação em duas etapas: um administrador pode exigi-la para a instância inteira, para um usuário ou para uma equipe, a partir das páginas de administração.
• As tentativas: cinco códigos errados bloqueiam novas tentativas por 15 minutos.
• As contas de sua equipe: as páginas de administração gerenciam os usuários, os sites e as equipes da instância inteira.

Guarde TWO_FACTOR_ENCRYPTION_KEY com seus backups: a documentação avisa que perder ou mudar essa chave torna ilegíveis os segredos armazenados, e cada usuário precisa então configurar de novo a autenticação em duas etapas.

Acrescentar um site e o script de rastreamento dele

1. Em Websites, clique em Add website.
2. Dê um nome ao site e depois informe o domínio dele: o Umami o usa para tirar suas próprias páginas da lista de origens.
3. Abra Edit nesse site e copie o código da seção Tracking code.
4. Cole-o no <head> de suas páginas e visite seu site: os dados aparecem logo no painel.

<script defer src="https://stats.example.com/script.js" data-website-id="your-website-id"></script>

• Nada aparece? A documentação sugere a aba de rede das ferramentas de desenvolvimento do navegador: as requisições para sua instância devem sair sem erro.
• Next.js: acrescente o código com o componente next/script em vez de uma tag <script> simples.
• data-domains limita o rastreamento a seus domínios de produção, o que mantém seus ambientes de teste fora das estatísticas.
• Suas próprias visitas são excluídas site por site, a partir do console do navegador, com localStorage.setItem('umami.disabled', 1).

Um nome de script próprio

Alguns bloqueadores de anúncios bloqueiam tudo o que parece medição de audiência. Auto-hospedado, o Umami já é servido a partir de seu próprio domínio, e duas variáveis vão mais longe: TRACKER_SCRIPT_NAME dá ao script outro nome que não script.js, e COLLECT_API_ENDPOINT renomeia o endpoint de coleta, no lugar de /api/send. O script passa então a chamar sozinho o novo endpoint; em suas páginas, só muda a origem do código de rastreamento.

TRACKER_SCRIPT_NAME: "stats.js"
COLLECT_API_ENDPOINT: "/api/collect"

As configurações úteis

Estas variáveis de ambiente vão no serviço umami do compose.yaml, e depois docker compose up -d recria o contêiner para levá-las em conta:

Os backups

Tudo o que o Umami guarda fica no banco PostgreSQL dele: contas, sites, equipes e estatísticas. Exporte-o todos os dias e logo antes de cada atualização: em auto-hospedagem, esses dados são guardados sem limite de duração. Ao lado do banco, o arquivo .env guarda os segredos que o tornam utilizável:

Exportar o banco em funcionamento

pg_dump faz uma exportação coerente enquanto o banco está em uso. O formato personalizado, -Fc, é compactado e se restaura com pg_restore:

docker compose exec -T db pg_dump -U umami -d umami -Fc > umami-$(date +%F).dump

Agende esse comando no servidor pelo menos uma vez por dia, faça a triagem das exportações, que se acumulam, e envie uma cópia para outro lugar. Guardadas no disco do servidor, essas exportações também entram nos backups noturnos dele.

Restaurar

1. Pare o Umami, deixando o banco em funcionamento: docker compose stop umami.
2. Restaure a exportação no banco, substituindo os objetos existentes.
3. Reinicie o Umami e verifique se seus sites e as estatísticas deles estão lá.

docker compose stop umami
docker compose exec -T db pg_restore -U umami -d umami --clean --if-exists < umami-YYYY-MM-DD.dump
docker compose start umami

Repita esse exercício de tempos em tempos, em uma cópia: é assim que você verifica se um backup funciona.

As atualizações

A documentação dá dois comandos, a partir da pasta do compose.yaml. O banco continua no volume dele:

docker compose pull
docker compose up --force-recreate -d

Ao reiniciar, o contêiner aplica sozinho as migrações do esquema. A versão 3.4.0, de 17 de setembro de 2026, trazia duas, para as anotações e as chaves de API; a versão 3.4.1, de 23 de outubro de 2026, não traz nenhuma. Após uma atualização principal, como a passagem para a versão 3, a documentação sugere executar ANALYZE no PostgreSQL para que os painéis recuperem a velocidade:

docker compose exec db psql -U umami -d umami -c "ANALYZE;"

• As notas de versão dizem o que cada versão muda. A versão 3.4.1 é uma correção de segurança que atualiza o Next.js e a imagem de base Node.js; as notas dela pedem a toda instância auto-hospedada que atualize baixando de novo a imagem.
• A partir de uma versão 2 com MySQL: a versão 3 deixou de suportar o MySQL. O guia de migração do projeto leva os dados para o PostgreSQL na versão 2.19.0, antes da passagem para a versão 3.
• O próprio PostgreSQL: mantenha a tag postgres:15-alpine do arquivo. Passar a uma nova versão principal do PostgreSQL exige uma exportação e uma restauração, ou pg_upgrade.

Quem faz o quê em um VPS gerenciado

A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o Umami continua sendo seu software, com as configurações e os dados dele.

Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.