Alojar Umami num VPS gerido: as estatísticas dos seus sites no seu servidor

O que faz o Umami

O Umami é uma plataforma de análise web e de produto, de código aberto. A sua documentação descreve uma ferramenta que reúne a audiência, as campanhas, o comportamento dos visitantes, as conversões, a retenção e as receitas, da primeira visita aos resultados que contam para a sua atividade. Está escrito em TypeScript sobre Next.js, e a sua imagem Docker corre com uma conta sem privilégios.

• A aquisição: páginas vistas, visitantes, fontes de tráfego, países, dispositivos e atividade em tempo real, com campanhas UTM, ligações curtas e píxeis de rastreamento.
• O comportamento: eventos personalizados, percursos, gravações de sessões, mapas de calor, segmentos, coortes e retenção.
• A conversão: objetivos, funis, atribuição e acompanhamento das receitas por página e por campanha.
• A partilha: painéis, equipas, um endereço de partilha público, uma API e um servidor MCP de leitura para o seu assistente de IA.
• Os sites modernos: a FAQ indica que o Umami acompanha sozinho a navegação entre páginas nas aplicações de página única, sem nenhuma definição adicional.

Uma instância acompanha vários sites: cada um recebe o seu próprio identificador e o seu script de rastreamento, e os seus colegas orientam-se através das contas e das equipas.

O que permite a licença MIT

O Umami é publicado sob a licença MIT, em nome da Umami Software, Inc. Esta concede, gratuitamente, o direito de utilizar, copiar, modificar, fundir, publicar, distribuir, sublicenciar e vender cópias do software. Pode, portanto, fazê-lo correr para a sua empresa e para os sites dos seus clientes, sem licença para comprar.

A sua única condição: o aviso de direitos de autor e o aviso de permissão acompanham todas as cópias ou partes substanciais do software. Como qualquer licença MIT, fornece o software «tal como está», sem garantia.

Cookies e dados pessoais: o que diz o projeto

A documentação apresenta o Umami como uma ferramenta de estatísticas sem cookies, sem rastreamento entre sites e sem recolha automática de dados pessoais. Autoalojado, mantém as suas estatísticas no seu próprio servidor: é você que decide onde ficam e durante quanto tempo.

Três definições do script de rastreamento vão mais longe, se o desejar: data-exclude-search retira os parâmetros de pesquisa dos URL registados, 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 assinala que esta última definição não constitui, por si só, uma solução completa de gestão do consentimento.

Se identificar os visitantes com sessão iniciada com data-distinct-id ou umami.identify(), a documentação recomenda um identificador de utilizador 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 o Docker Compose e o PostgreSQL

O repositório fornece um docker-compose.yml que arranca o Umami e a sua base de dados PostgreSQL. Desde a versão 3, o PostgreSQL é a única base de dados suportada, na versão 12.14 no mínimo, e a documentação recomenda configurá-lo no fuso horário UTC. Num servidor com o Docker instalado, crie uma pasta e comece pelos seus segredos, gerados aleatoriamente com o 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 depois este compose.yaml ao lado. Retoma o ficheiro do projeto na versão 3.4.1, com duas alterações: os segredos vêm do ficheiro .env, e a porta só é publicada 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 ligação à base de dados. A palavra-passe hexadecimal entra tal como está; uma palavra-passe com caracteres especiais exigiria uma codificação percentual.
• APP_SECRET: uma cadeia aleatória que protege os tokens de autenticação, própria de cada instalação. No código da versão 3.4.1, entra também no cálculo dos identificadores de sessão: mantenha-a estável.
• TWO_FACTOR_ENCRYPTION_KEY: 64 caracteres hexadecimais que cifram os segredos da autenticação de dois fatores. Sem ela, ninguém pode ativar a autenticação de dois fatores.
• No arranque, o contentor verifica a ligação e a versão da base de dados e aplica depois ele próprio as migrações do esquema. Na primeira execução, cria as tabelas e a conta admin. A sonda /api/heartbeat responde {"ok":true} assim que o Umami está pronto.
• A etiqueta latest acompanha a última versão publicada. O registo do projeto publica também etiquetas de versão, como 3.4.1, para fixar a que utiliza.

A documentação de instalação não indica nenhum valor de memória nem de processador. O tamanho depende do tráfego dos sites acompanhados e do volume de dados que conserva. Num VPS gerido, descreva-nos a sua utilização e recomendamos-lhe o tamanho adequado.

HTTPS: o proxy inverso

O Umami escuta em HTTP na porta 3000, e a documentação sugere servi-lo atrás do seu servidor web, através de um proxy inverso. Atribua-lhe um subdomínio próprio, como stats.example.com, que aponte para o servidor com registos A e AAAA. Servir o Umami num caminho passa por BASE_PATH, uma variável lida na construção da aplicação: com a imagem publicada, o subdomínio é a via direta.

O proxy tem também de transmitir o endereço do visitante. O Umami lê-o nos cabeçalhos que recebe, entre os quais X-Real-IP e X-Forwarded-For: serve-se dele para distinguir os visitantes e para localizar o seu país. Se o seu proxy utilizar outro cabeçalho, CLIENT_IP_HEADER indica-o.

Com o Caddy

O Caddy obtém o certificado Let's Encrypt e ativa o HTTPS por si próprio. A sua diretiva reverse_proxy define X-Forwarded-For por predefiniçã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 Nginx da documentação do Umami, a escutar 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;
  }
}

O Certbot instala depois o certificado e encarrega-se de o renovar:

sudo certbot --nginx

O primeiro início de sessão: a conta admin e a autenticação de dois fatores

Ao criar a sua base de dados, o Umami abre uma conta de administrador: nome de utilizador admin, palavra-passe umami. A documentação pede que mude esta palavra-passe no primeiro início de sessão.

1. Abra o seu endereço HTTPS e inicie sessão com admin e umami.
2. Abra Settings a partir do botão de perfil na barra lateral, depois Profile, e clique em Change password.
3. No separador Security, ative a autenticação de dois fatores: leia o código QR com a sua aplicação de autenticação, introduza o código de seis algarismos e guarde depois num lugar seguro os dez códigos de recuperação, que só são apresentados uma vez.

• Exigir a autenticação de dois fatores: um administrador pode impô-la a toda a instância, a um utilizador ou a uma equipa, a partir das páginas de administração.
• As tentativas: cinco códigos errados bloqueiam as tentativas seguintes durante 15 minutos.
• As contas da sua equipa: as páginas de administração gerem os utilizadores, os sites e as equipas de toda a instância.

Guarde TWO_FACTOR_ENCRYPTION_KEY com as suas cópias de segurança: a documentação avisa que perder ou mudar esta chave torna ilegíveis os segredos guardados, e cada utilizador tem então de configurar de novo a sua autenticação de dois fatores.

Acrescentar um site e o respetivo script de rastreamento

1. Em Websites, clique em Add website.
2. Dê um nome ao site e depois o seu domínio: o Umami serve-se dele para retirar as suas próprias páginas da lista das fontes de tráfego.
3. Abra Edit nesse site e copie o código da secção Tracking code.
4. Cole-o no <head> das suas páginas e visite depois o 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 o separador de rede das ferramentas de programação do navegador: os pedidos para a sua instância devem partir sem erros.
• Next.js: acrescente o código com o componente next/script em vez de uma simples etiqueta <script>.
• data-domains limita o rastreamento aos seus domínios de produção, o que deixa os seus ambientes de teste fora das estatísticas.
• As suas próprias visitas excluem-se site a site, a partir da consola do navegador, com localStorage.setItem('umami.disabled', 1).

Um nome de script próprio

Alguns bloqueadores de anúncios bloqueiam tudo o que se assemelhe a estatísticas. Em autoalojamento, o Umami já é servido a partir do 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 muda o nome do ponto de recolha, em vez de /api/send. O script chama então sozinho o novo ponto de recolha; nas suas páginas, só muda a origem do código de rastreamento.

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

As definições úteis

Estas variáveis de ambiente entram no serviço umami do compose.yaml, e depois docker compose up -d recria o contentor para as ter em conta:

As cópias de segurança

Tudo o que o Umami conserva vive na sua base de dados PostgreSQL: contas, sites, equipas e estatísticas. Exporte-a todos os dias e logo antes de cada atualização: em autoalojamento, estes dados são conservados sem limite de tempo. Ao lado da base de dados, o ficheiro .env contém os segredos que a tornam utilizável:

Exportar a base de dados em funcionamento

O pg_dump faz uma exportação coerente enquanto a base de dados está a ser utilizada. O formato personalizado, -Fc, é comprimido e restaura-se com o pg_restore:

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

Agende este 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. Colocadas no disco do servidor, estas exportações entram também nas suas cópias de segurança noturnas.

Restaurar

1. Pare o Umami, deixando a base de dados a funcionar: docker compose stop umami.
2. Restaure a exportação na base de dados, substituindo os objetos existentes.
3. Reinicie o Umami e verifique depois que os seus sites e as respetivas estatísticas 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 este exercício de vez em quando, numa cópia: é assim que verifica que uma cópia de segurança funciona.

As atualizações

A documentação dá dois comandos, a partir da pasta do compose.yaml. A base de dados mantém-se no seu volume:

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

No reinício, o contentor 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. Depois de 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 sua rapidez:

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

• As notas de versão dizem o que muda em cada versão. 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 suas notas pedem a todas as instâncias autoalojadas que atualizem, transferindo de novo a imagem.
• A partir de uma versão 2 em MySQL: a versão 3 deixou de suportar o MySQL. O guia de migração do projeto transfere 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 etiqueta postgres:15-alpine do ficheiro. Passar para uma nova versão principal do PostgreSQL exige uma exportação e um restauro, ou o pg_upgrade.

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o Umami continua a ser o seu software, com as suas definições e os seus dados.

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.