Instalar Umami Analytics na VPS: Guia Completo de Rastreamento

O que é o Umami e por que migrar para um ambiente self-hosted?

No cenário atual de privacidade digital, onde regulamentações como a LGPD (Lei Geral de Proteção de Dados) exigem transparência no tratamento de informações pessoais, as ferramentas de análise tradicionais têm se tornado um risco potencial para muitos administradores de sites e desenvolvedores. O Umami Analytics surge como uma alternativa robusta, leve e open source, projetada especificamente para respeitar a privacidade dos usuários enquanto fornece dados precisos sobre o tráfego do seu site.

Diferente de soluções proprietárias que exigem scripts pesados e enviam dados para servidores terceirizados no exterior, o Umami permite que você tenha um dashboard analítico próprio rodando em sua própria infraestrutura. Isso significa controle total sobre os dados, conformidade facilitada com leis de privacidade e uma experiência de navegação mais rápida para seus visitantes, já que o script de rastreamento é extremamente leve.

Neste tutorial técnico, vamos guiar você através do processo completo de instalação do Umami em uma VPS Linux utilizando Docker Compose. Este método garante consistência, facilidade de manutenção e escalabilidade, sendo a escolha ideal para sysadmins e profissionais de TI que buscam uma solução self-hosted analytics confiável.

Pré-requisitos e Preparação do Ambiente

Antes de iniciar a instalação, certifique-se de que sua VPS atenda aos requisitos mínimos. Para a maioria dos projetos pessoais ou pequenas empresas, uma instância com 1 vCPU e 512MB de RAM é suficiente, embora recomendemos 1GB para melhor performance em casos de alto tráfego.

O sistema operacional deve ser uma distribuição Linux moderna (Ubuntu, Debian, CentOS Stream ou Rocky Linux). Para este guia, assumiremos que você já possui acesso SSH com privilégios de root ou um usuário com sudo configurado. Além disso, é fundamental ter o Docker e o Docker Compose instalados na máquina.

Se você ainda não possui o Docker instalado, execute os comandos abaixo para Ubuntu/Debian:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Para verificar se a instalação foi bem-sucedida, rode:

docker --version
docker compose version

Além disso, você precisará de um domínio apontando para o IP da sua VPS e certificados SSL (preferencialmente via Let's Encrypt) para garantir que a conexão seja segura. O Umami não funcionará corretamente se tentarmos acessar scripts de rastreamento através de HTTP não seguro em muitos navegadores modernos.

Passo 1: Configuração do Banco de Dados PostgreSQL

O Umami utiliza o PostgreSQL como seu banco de dados principal. Embora seja possível usar SQLite para testes locais, a configuração com Docker Compose e PostgreSQL é a recomendação oficial para ambientes de produção, garantindo integridade dos dados e melhor concorrência.

Crie um diretório dedicado para a instalação do Umami em sua VPS:

mkdir -p ~/umami && cd ~/umari

Dentro desse diretório, criaremos o arquivo docker-compose.yml. Este arquivo orquestrará os contêineres necessários: o banco de dados e a aplicação principal. O conteúdo do arquivo deve ser estruturado da seguinte maneira:

version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:secret@db:5432/umami
      UI_URL: https://seu-dominio.com
      APP_SECRET: substitua-por-uma-string-aleatoria-segura
    depends_on:
      - db
    restart: always
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: secret
    volumes:
      - ~/umami/db-data:/var/lib/postgresql/data
    restart: always

Atenção às variáveis de ambiente:

• DATABASE_URL: Define a conexão com o banco. A estrutura segue o padrão postgresql://usuario:senha@host:porta/banco.
• UI_URL: Substitua https://seu-dominio.com pelo domínio real do seu site. Isso é crucial para que o script de rastreamento seja injetado corretamente.
• APP_SECRET: Uma chave aleatória usada para criptografar sessões e cookies. Gere uma string longa e complexa para segurança máxima.

Ao salvar este arquivo, execute o comando para baixar as imagens e iniciar os contêineres em segundo plano:

docker compose up -d

Aguarde alguns instantes até que a inicialização do banco de dados e da aplicação seja concluída. Você pode monitorar o log com docker compose logs -f umami.

Passo 2: Acesso Inicial e Criação da Conta Administrativa

Com os contêineres rodando, a interface web do Umami estará acessível na porta 3000. No entanto, para acessar via HTTPS e domínio correto, precisamos configurar um proxy reverso.

Se você ainda não configurou um servidor web como Nginx ou Apache, o caminho mais rápido e seguro é utilizar o Traefik ou o Caddy, que automatizam a emissão de certificados SSL. Para este tutorial, assumiremos uma configuração padrão com Nginx, que é muito comum em VPSs.

Crie um arquivo de configuração no seu servidor web (ex: /etc/nginx/sites-available/umami):

server {
    listen 80;
    server_name analytics.seudominio.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Após configurar o Nginx e ativar o site, reinicie o serviço:

sudo systemctl restart nginx

Agora, acesse https://analytics.seudominio.com no seu navegador. Na primeira execução, o Umami criará automaticamente o banco de dados e solicitará a criação de uma conta de administrador. Use um e-mail forte e uma senha complexa.

Dica de Segurança: Após criar a conta, é recomendável remover a rota de registro público ou proteger o acesso à página de login com autenticação básica do Nginx se o seu painel for exposto publicamente sem necessidade de cadastro adicional.

Passo 3: Integração com o Site e Configuração do Rastreamento

Com a conta criada, você verá o dashboard principal. O próximo passo é adicionar o site que deseja monitorar. Clique em "Adicionar Site" no menu lateral.

1. Nome do Site: Insira o nome amigável (ex: "Blog Principal").
2. URL do Site: Insira a URL exata que será usada pelos visitantes (ex: https://meusite.com.br). Isso deve corresponder ao domínio real.
3. Domínio do Script: Este campo é preenchido automaticamente com o domínio onde o Umami está instalado. Não altere, a menos que tenha uma configuração de subdomínio específica para os scripts.

Ao salvar, o sistema gerará um snippet de código JavaScript. Copie este código e cole no cabeçalho (<head>) de todas as páginas do seu site, ou em um plugin de gerenciamento de tags (como Google Tag Manager) se você utilizar tal estrutura.

O script tem uma aparência similar a esta:

<script async="" defer="" src="https://analytics.seudominio.com/script.js"></script>

Este é o coração do rastreamento web open source. Note que não há cookies de rastreamento cruzado, nem coleta de dados pessoais identificáveis (PII). O Umami registra apenas o evento, a página, o referrer e as dimensões técnicas (resolução, navegador) sem armazenar IPs ou nomes de usuários.

Passo 4: Personalização do Dashboard e Métricas Chave

Uma das grandes vantagens de ter um hosting analytics próprio é a capacidade de personalizar completamente o que você vê. O Umami oferece dashboards padrão, mas permite a criação de visualizações customizadas.

Explore as abas disponíveis:

• Página Inicial: Mostra visitas únicas, páginas por visita e tempo médio na página.
• Relatórios: Detalha as páginas mais visitadas, origem do tráfego (referrers), sistemas operacionais, navegadores e dispositivos.
• Mais Rápidos/Mais Lentos: Identifica gargalos de performance em suas páginas internas.

Para profissionais de BI e marketing, a aba "Funis" pode ser extremamente útil. Você pode definir uma sequência de eventos (ex: Visita à Landing Page -> Clique em Comprar -> Página de Checkout) para analisar a conversão real do usuário sem depender de integrações complexas com CRMs externos.

Lembre-se de configurar o filtro de bots. Por padrão, o Umami já filtra bots conhecidos, mas você pode adicionar regras adicionais na seção de configurações se notar tráfego suspeito ou crawlers específicos que estejam poluindo seus dados.

Passo 5: Manutenção, Backup e Segurança

A infraestrutura docker analytics facilita a manutenção. No entanto, como proprietário dos dados, a responsabilidade pelo backup é sua. Dados de análise são valiosos para tomada de decisão a longo prazo e não devem ser perdidos.

Backup do Banco de Dados

O banco de dados PostgreSQL está montado no volume ~/umami/db-data. Realize backups regulares deste diretório. Você pode automatizar isso com um script cron simples:

0 2 * * * tar -czf /backups/umami-db-$(date +\%Y\%m\%d).tar.gz ~/umami/db-data

Este comando compactará o banco de dados diariamente às 02:00 da manhã e enviará para um diretório de backups.

Atualizações do Umami

Para atualizar a aplicação para a versão mais recente, basta navegar até o diretório de instalação e executar:

cd ~/umami
docker compose pull
docker compose up -d

O Docker Compose detectará novas imagens no repositório ghcr.io, fará o download e reiniciará os contêineres com a nova versão, mantendo os dados do banco intactos.

Hardening de Segurança

Além de usar HTTPS, considere as seguintes práticas:

• Alterar a porta padrão se não estiver usando um proxy reverso (embora o uso de proxy seja recomendado).
• Configurar Fail2Ban para bloquear tentativas de login falhas na interface do Umami.
• Restringir o acesso ao painel administrativo via firewall, permitindo conexões apenas do seu IP se você for o único usuário do sistema.

Vantagens Competitivas: Privacidade e Performance

Ao escolher o Umami Analytics na VPS, você está optando por uma filosofia de desenvolvimento que coloca a eficiência acima da complexidade. Diferente de soluções que consomem recursos significativos do servidor com processamento pesado de dados em tempo real, o Umami é escrito em Node.js e otimizado para alta performance com baixo consumo de memória.

Além disso, ao utilizar uma solução self-hosted analytics, você elimina a dependência de terceiros. Se a empresa por trás de uma ferramenta SaaS decidir mudar seus termos de serviço ou aumentar os preços, seu histórico de dados permanece seguro e acessível em sua infraestrutura.

Para desenvolvedores, o código aberto permite auditoria completa da lógica de rastreamento. Você pode verificar exatamente quais dados estão sendo coletados e garantir que nenhuma informação sensível esteja vazando para servidores externos. Isso é essencial para empresas que operam em setores regulados, como saúde, finanças ou governo.

Conclusão

A instalação do Umami em uma VPS Linux através do Docker Compose é um processo direto e poderoso. Ele oferece o equilíbrio perfeito entre funcionalidade rica e respeito à privacidade do usuário final. Ao seguir os passos descritos — desde a preparação do ambiente PostgreSQL até a configuração do proxy reverso e integração do script — você estabelece uma base sólida para monitoramento de dados.

Este setup não apenas melhora a velocidade do seu site ao remover scripts pesados de terceiros, mas também fortalece a confiança dos seus usuários ao demonstrar um compromisso claro com a privacidade dados web. Para sysadmins e devs que buscam controle total, o Umami é, sem dúvida, uma das melhores escolhas no ecossistema de BI e dashboards self-hosted.

Experimente hoje mesmo migrar para uma análise transparente e eficiente. Seu servidor agradece pela leveza, e seus usuários agradecem pela privacidade.