Como Instalar o Umami Analytics na VPS

Por que escolher o Umami Analytics para sua VPS?

No cenário atual de privacidade digital e conformidade com regulamentações como a LGPD, o rastreamento tradicional de sites está sob escrutínio rigoroso. Plataformas como Google Analytics exigem cookies complexos e transferem dados para servidores terceirizados, o que pode ser um ponto crítico para empresas que priorizam a soberania dos dados. A solução ideal para muitos profissionais de TI é o Umami Analytics, uma alternativa leve, open source e focada na privacidade.

Diferente de gigantes como Matomo ou ferramentas mais complexas como Plausible Analytics, o Umami foi construído com uma arquitetura minimalista em mente. Ele utiliza menos recursos de CPU e memória, tornando-o extremamente adequado para rodar em instâncias VPS de pequeno porte. Para sysadmins que buscam manter o controle total sobre a infraestrutura de dados, instalar o Umami em um servidor próprio oferece transparência total sobre o que é coletado e como os dados são armazenados.

Neste tutorial, demonstraremos como realizar a instalação completa do Umami Analytics em uma VPS Linux (Ubuntu/Debian), utilizando Docker para garantir isolamento, facilidade de manutenção e escalabilidade. Abordaremos desde o provisionamento do banco de dados até a configuração final do painel administrativo.

Pré-requisitos e Preparação do Ambiente

Antes de iniciar a instalação, é fundamental garantir que seu ambiente esteja preparado. Você precisará de acesso root ou um usuário com privilégios sudo na sua VPS. Recomendamos o uso de um sistema operacional moderno e estável, como Ubuntu 22.04 LTS ou Debian 12.

A principal vantagem de utilizar containers para este tipo de aplicação é a portabilidade. O Umami depende de duas tecnologias principais: Node.js (para a aplicação web) e PostgreSQL (para o banco de dados). Ao usar Docker, abstraiamos essas dependências do sistema operacional hospedeiro, evitando conflitos de bibliotecas.

Certifique-se de que o firewall da sua VPS esteja configurado para permitir apenas as conexões necessárias. Por padrão, você precisará liberar as portas 80 (HTTP) e 443 (HTTPS) se planeja usar um proxy reverso como Nginx ou Traefik, além das portas internas do Docker.

Passo 1: Instalando Docker e Docker Compose

O primeiro passo é instalar o Docker Engine em sua VPS. Esta ferramenta permite criar, implantar e executar aplicações usando containers. O Docker Compose, por sua vez, facilita a definição e execução de aplicativos multicontenedores.

Inicie a atualização dos pacotes do sistema:

sudo apt update
sudo apt upgrade -y

Instale os pré-requisitos necessários para adicionar o repositório oficial do Docker:

sudo apt install ca-certificates curl gnupg lsb-release -y

Adicione a chave GPG oficial do Docker e adicione o repositório:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Atualize o índice do pacote novamente e instale o Docker Engine:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

Verifique a instalação executando um container de teste:

sudo docker run hello-world

Passo 2: Configurando o Banco de Dados PostgreSQL

O Umami requer um banco de dados relacional para armazenar eventos, páginas e métricas. O PostgreSQL é a escolha recomendada pela equipe do projeto devido à sua estabilidade e performance.

Crie uma pasta dedicada para a configuração do projeto:

sudo mkdir -p /opt/umami && cd /opt/umami

Dentro desta pasta, crie um arquivo docker-compose.yml. Este arquivo definirá os serviços que serão executados. Para uma instalação inicial e segura, vamos definir o banco de dados e a aplicação do Umami em um único arquivo.

nano docker-compose.yml

Cole a seguinte configuração no arquivo. Certifique-se de alterar as variáveis UMAMI_DB_USER, UMAMI_DB_PASSWORD e POSTGRES_PASSWORD para senhas fortes e únicas:

version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:SEU_PASSWORD_AQUI@db:5432/umami
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: umami
      DB_PASSWORD: SEU_PASSWORD_AQUI
      APP_SECRET: GERAR_UMA_STRING_ALEATORIA_SEGURA_AQUI
    depends_on:
      - db
    restart: always

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: SEU_PASSWORD_AQUI
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always

volumes:
  umami-db-data:

Nota técnica: A variável APP_SECRET é crucial para a segurança das sessões do usuário. Use uma ferramenta de geração de senhas ou o comando openssl rand -hex 32 para gerar esta string.

Passo 3: Iniciando os Contêineres e Verificando a Instalação

Agora que a configuração está pronta, podemos iniciar os serviços. Execute o comando abaixo na mesma pasta onde criou o arquivo docker-compose.yml:

sudo docker compose up -d

O sinalizador -d executa os contêineres em segundo plano (modo detached). O Docker irá baixar as imagens necessárias, configurar o banco de dados PostgreSQL e iniciar a aplicação Umami.

Para verificar se tudo está funcionando corretamente, liste os contêineres em execução:

sudo docker ps

Você deve ver dois contêineres: um para o serviço umami e outro para o banco de dados db. Ambos devem ter o status "Up".

Acesse o endereço IP público da sua VPS ou domínio configurado na porta 3000 (ex: http://seu-dominio.com:3000). Você deverá ver a tela de login do Umami.

Passo 4: Configuração Inicial e Login Administrativo

A primeira vez que você acessar o painel, será solicitado que crie uma conta de administrador. As credenciais padrão para o primeiro login são:

• Usuário: admin
• Senha: umami

Importante: Imediatamente após o primeiro login, altere a senha e o nome de usuário padrão. Navegue até as configurações da conta no canto superior direito para garantir que suas credenciais sejam únicas e seguras.

Após fazer login, você será direcionado ao painel principal. O Umami oferece uma interface limpa e intuitiva. Você pode começar a adicionar seus sites clicando no botão "Adicionar Website" ou "Add Website".

Passo 5: Integrando o Script de Rastreamento

Para coletar dados, você precisa inserir um snippet de JavaScript na sua aplicação web. No painel do Umami, após adicionar um site, você verá uma seção chamada "Tracker Code".

O código padrão se parece com isto:

<script async defer src="https://seu-dominio.com/umami.js" data-website-id="SEU_ID_DO_SITE"></script>

Copie este script e cole no cabeçalho (<head>) de todas as páginas do seu site que deseja rastrear. Diferente do Google Analytics, o Umami não requer consentimento explícito para cookies técnicos de análise funcional em muitas jurisdições, pois ele não usa cookies identificáveis individualmente e os dados são anonimizados por padrão.

Passo 6: Segurança e Otimização

A instalação básica funciona bem, mas para um ambiente de produção robusto, é essencial implementar camadas adicionais de segurança e otimização.

Configurando Proxy Reverso com Nginx

Acesso direto à porta 3000 não é recomendado. Configure o Nginx para atuar como um proxy reverso, permitindo o uso de HTTPS (SSL/TLS) e melhorando a performance.

sudo apt install nginx certbot python3-certbot-nginx -y

Crie um arquivo de configuração no Nginx em /etc/nginx/sites-available/umami:

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

    location / {
        proxy_pass http://127.0.0.1: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;
    }
}

Ative a configuração e solicite o certificado SSL:

sudo ln -s /etc/nginx/sites-available/umami /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo certbot --nginx -d analytics.seudominio.com

Habilitando Logs e Monitoramento

Para manter a saúde do seu servidor, monitore o uso de recursos. Como o Umami é leve, ele não deve consumir muitos recursos, mas é bom acompanhar.

sudo docker stats

Este comando mostra em tempo real o uso de CPU e memória dos seus contêineres. Se você precisar de dashboards mais avançados para infraestrutura, pode integrar o Docker com ferramentas como Grafana, embora para a maioria dos casos, os logs do próprio sistema (journalctl) sejam suficientes.

Comparativo Rápido: Umami vs Outras Ferramentas Self-Hosted

Muitos administradores de sistemas se deparam com a escolha entre várias ferramentas open source. É útil entender onde o Umami se encaixa no ecossistema:

• Matomo Analytics VPS: O Matomo é extremamente poderoso e compatível com o Google Analytics, mas é mais pesado e complexo de configurar. Requer mais recursos de banco de dados e processamento.
• Plausible Analytics Servidor Próprio: O Plausible é muito similar ao Umami em filosofia (leve e privado). No entanto, o Umami tem crescido rapidamente com uma comunidade ativa e oferece funcionalidades como mapas de calor nativos em versões mais recentes, enquanto o Plaussible foca estritamente em métricas básicas.
• PostHog Self-Hosted Tutorial: O PostHog é uma plataforma completa de produto analytics, focada em comportamento do usuário, funis e A/B testing. É muito mais complexo que o Umami e requer infraestrutura robusta (Kafka, ClickHouse, etc.). Use PostHog para engenharia de produto; use Umami para tráfego web simples.
• Instalar Metabase VPS: O Metabase é uma ferramenta de Business Intelligence (BI) para visualizar dados estruturados. Ele não serve para rastreamento de visitantes de site diretamente, mas pode ser usado para analisar dados exportados do Umami se você tiver necessidades avançadas de relatórios.
• Grafana Dashboard VPS: O Grafana é uma ferramenta de visualização. Você pode conectar o banco de dados PostgreSQL do Umami ao Grafana para criar dashboards personalizados, mas o Umami já vem com seu próprio painel integrado.

Manutenção e Backup

A manutenção de uma instalação Docker é simples. Para atualizar o Umami para a última versão:

cd /opt/umami
sudo docker compose pull
sudo docker compose up -d

O banco de dados é armazenado em um volume Docker nomeado (umami-db-data). Para fazer backup, você pode parar os contêineres e copiar o diretório do volume ou usar scripts de dump do PostgreSQL.

sudo docker exec -it umami_db_1 pg_dump -U umami umami > umami_backup.sql

Guarde este arquivo .sql em um local seguro. Isso garante que, mesmo se seu servidor falhar, você possa restaurar seus dados históricos de tráfego.

Conclusão

Instalar o Umami Analytics em uma VPS é uma das decisões mais inteligentes para profissionais que valorizam a privacidade, a simplicidade e o controle. Ao contrário de soluções monolíticas como Matomo ou plataformas complexas como PostHog, o Umami entrega exatamente o necessário: métricas precisas, sem bloatware.

A combinação de Docker, PostgreSQL e Nginx cria uma base sólida e escalável. Você tem a liberdade de personalizar, exportar dados para BI externo via Metabase ou Grafana quando necessário, e mantém seus dados sob total controle. Com menos de 50MB de RAM em uso na maior parte do tempo, o Umami prova que analytics de qualidade não precisa ser pesado.

Agora que você domina a instalação, explore as configurações avançadas de cookies personalizados e integrações de API para levar sua análise de dados ao próximo nível.