Cómo instalar Umami en un VPS

Requisitos previos

Usa Ubuntu 22.04 o 24.04 con SSH, IP pública y al menos 1 GB de RAM para una instancia pequeña. Crea un registro A como analytics.example.com y permite los puertos 80 y 443. También necesitas un destino de backup y un secreto de aplicación largo y aleatorio.

Umami guarda los eventos en PostgreSQL, así que el disco depende del tráfico y la retención. No expongas PostgreSQL a internet. Solo el reverse proxy debe ser público.

Paso 1, Conectarte a tu servidor

Conéctate y prepara una carpeta dedicada:

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

Comprueba que 80, 443 y el puerto interno de la aplicación estén libres. El Compose y .env deben ser legibles solo por administradores.

Paso 2, Instalar Docker y Docker Compose

Instala Docker Engine y el plugin de Compose con las instrucciones actuales de Docker para Ubuntu. Confirma la instalación:

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

Usa la sintaxis actual de Compose y una fuente de paquetes soportada. Mantén el host actualizado antes de publicar el endpoint.

Paso 3, Ejecutar Umami con Docker Compose

Crea .env con valores que no se repitan en ningún otro sitio:

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

Esto es crítico — sin APP_SECRET los tokens de autenticación no están protegidos correctamente. Genera el valor con openssl rand -hex 32 y no lo compartas. La contraseña de DATABASE_URL debe coincidir con POSTGRES_PASSWORD, codificando los caracteres reservados si el valor generado los contiene. Crea 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:

Configura la zona horaria de PostgreSQL a UTC. Umami espera UTC para una agregación correcta de estadísticas.

Arranca y revisa el stack:

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

Fija los tags de imagen que hayas probado antes de usarlo para reporting importante.

Paso 4, Configurar el proxy inverso

Envía analytics.example.com desde Caddy, Nginx u otro proxy soportado a 127.0.0.1:3000. Termina TLS en el proxy, conserva las cabeceras de host y protocolo y mantén privado el puerto 3000. El script debe cargarse por HTTPS si el sitio también lo usa, o el navegador puede bloquearlo por mixed content.

En el firewall deja abiertos solo SSH, 80 y 443. Prueba la renovación del certificado y confirma que el proxy reenvía el header Host correcto. Detrás de un CDN o proxy, define las variables de entorno CLIENT_IP_HEADER y FORCE_SSL en el servicio de Umami para una geolocalización IP correcta.

Paso 5, Primer acceso y configuración inicial

Abre https://analytics.example.com y completa el primer acceso. Cambia de inmediato las credenciales por defecto (admin / umami). Crea una entrada para el sitio, copia el snippet de tracking y añádelo a la web que quieras medir.

Carga la web en una ventana privada y confirma que aparece una visita. Revisa hostname y zona horaria antes de invitar a otros usuarios. Recoge solo los datos necesarios y documenta las obligaciones de consentimiento que correspondan.

Mantenimiento

Haz backup de PostgreSQL y APP_SECRET juntos. Controla la retención y el volumen con df -h y métricas de PostgreSQL. Actualiza Umami tras revisar las notas de versión, ejecuta la migración soportada y comprueba que los informes sigan funcionando.

Si dejan de llegar eventos, revisa primero la petición de red del navegador, después los logs del proxy y por último los de Umami. No borres el volumen para solucionar un problema de tracking.