Como instalar o Umami em uma VPS

Pré-requisitos

Use Ubuntu 22.04 ou 24.04 com SSH, IP público e pelo menos 1 GB de RAM para uma pequena instância de análise de dados. Crie um registro A, como analytics.example.com, e permita as portas 80 e 443. Você também precisa de um destino para backups e de um segredo longo e aleatório para o aplicativo.

O Umami armazena dados de eventos no PostgreSQL, então o uso do disco depende do tráfego e do período de retenção. Não exponha o PostgreSQL à internet. Somente o proxy reverso deve ser público.

Etapa 1, conectando-se ao servidor

Conecte-se e prepare um diretório dedicado:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl
mkdir -p /opt/umami
cd /opt/umami
chmod 750 /opt/umami

Confira se as portas 80, 443 e a porta interna do aplicativo não estão ocupadas. Restrinja a leitura do arquivo Compose e de .env aos administradores.

Etapa 2, instalando o Docker e o Docker Compose

Instale o Docker Engine e o plugin Compose seguindo as instruções atuais do Docker para Ubuntu. Confirme a instalação:

docker --version
docker compose version
systemctl enable --now docker

Use a sintaxe Compose atual e uma fonte de pacotes com suporte. Mantenha o servidor atualizado antes de expor o endpoint de análise de dados.

Etapa 3, executando o Umami com Docker Compose

Crie .env com valores que não sejam usados em nenhum outro lugar:

POSTGRES_DB=umami
POSTGRES_USER=umami
POSTGRES_PASSWORD=REPLACE_WITH_A_RANDOM_VALUE
APP_SECRET=$(openssl rand -hex 32)
DATABASE_URL=postgresql://umami:REPLACE_WITH_A_RANDOM_VALUE@db:5432/umami

Isso é essencial, sem APP_SECRET os tokens de autenticação não ficam devidamente protegidos. Gere o valor com openssl rand -hex 32 e nunca o compartilhe. A senha em DATABASE_URL precisa corresponder a POSTGRES_PASSWORD, com codificação de URL se o valor gerado contiver caracteres reservados. Crie compose.yaml:

services:
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data

  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    restart: unless-stopped
    depends_on:
      - db
    environment:
      DATABASE_URL: ${DATABASE_URL}
      APP_SECRET: ${APP_SECRET}
    ports:
      - "127.0.0.1:3000:3000"

volumes:
  db_data:

Defina o fuso horário do PostgreSQL como UTC. O Umami espera UTC para agregar os dados analíticos corretamente.

Inicie o conjunto de serviços e confira o estado:

docker compose up -d
docker compose ps
docker compose logs --tail 100 umami

Fixe as tags das imagens testadas antes de usar a implantação para relatórios importantes.

Etapa 4, configurando o proxy reverso

Encaminhe analytics.example.com do Caddy, do Nginx ou de outro proxy compatível para 127.0.0.1:3000. Encerre o TLS no proxy, preserve os cabeçalhos originais do servidor e do protocolo e mantenha a porta 3000 privada. Se o site usa HTTPS, o script de medição também precisa ser carregado por HTTPS, caso contrário os navegadores podem bloqueá-lo como conteúdo misto.

Se você usa um firewall no servidor, permita somente SSH, 80 e 443. Teste a renovação do certificado e confira se o proxy envia o cabeçalho Host correto para o Umami. Atrás de uma CDN ou proxy, defina as variáveis de ambiente CLIENT_IP_HEADER e FORCE_SSL no serviço Umami para obter a geolocalização correta do IP.

Etapa 5, primeiro acesso e configuração inicial

Acesse https://analytics.example.com e conclua o primeiro login. Altere imediatamente as credenciais padrão de administrador (admin / umami). Crie uma entrada de site, copie o trecho de código de acompanhamento gerado e adicione-o ao site que você quer medir.

Abra o site em uma janela de navegação privada e confirme que uma visualização de página aparece. Confira o domínio e o fuso horário antes de convidar outras pessoas. Evite coletar dados desnecessários e documente os requisitos de consentimento aplicáveis ao seu público.

Manutenção

Faça backup do PostgreSQL e de APP_SECRET em conjunto. Controle o período de retenção e monitore o volume do banco de dados com df -h e métricas do PostgreSQL. Atualize o Umami após consultar as notas de versão, execute a migração da maneira compatível e confirme que os relatórios continuam carregando.

Se os eventos pararem de chegar, confira a solicitação de rede no navegador, os logs do proxy e os logs do Umami, nessa ordem. Não exclua o volume do banco de dados para corrigir um problema de acompanhamento.