Cómo instalar Umami Analytics en un VPS

Qué resuelve Umami y qué no

Umami registra visitas, páginas, referentes, dispositivos y eventos personalizados en una sola pantalla, sin cookies y sin enviar datos a terceros. Es analítica web, no una plataforma de marketing: no hay integración con Google Ads, ni modelos de atribución multicanal, ni segmentos de audiencia para remarketing.

Encaja bien si:

• Quieres saber qué páginas funcionan y de dónde llega la gente, sin más.
• Te molesta el banner de cookies y prefieres no tener que ponerlo por analítica.
• Trabajas con varios sitios o clientes y quieres separarlos por equipo.
• El informe de GA4 te resulta más lento de leer que útil.

No encaja si dependes de embudos de conversión avanzados, integración con la suite publicitaria de Google o análisis de cohortes complejos. Ahí GA4 sigue siendo la herramienta con más funciones, y es honesto decirlo.

Requisitos reales

La documentación oficial pide Node.js 18.18 o superior y PostgreSQL 12.14 o superior. Desde la versión 3, publicada en diciembre de 2024, PostgreSQL es la única base de datos soportada: el soporte para MySQL se retiró y las instalaciones antiguas deben migrar antes de actualizar.

El disco importa más de lo que parece: cada visita genera filas en las tablas de sesión y evento. Un sitio con 100.000 visitas al mes ocupa poco, pero diez sitios con eventos personalizados durante dos años suman. Planifica una política de retención desde el principio.

Si el VPS es pequeño, activa memoria de intercambio antes de instalar; la guía de configurar swap en Ubuntu evita que el arranque de Next.js muera por falta de memoria.

Instalar Umami con Docker Compose

El repositorio oficial trae un docker-compose.yml que levanta Umami y PostgreSQL juntos. Necesitas Docker en el VPS; si aún no lo tienes, sigue Docker en un VPS.

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

docker-compose.yml:

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    container_name: umami
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${DB_PASSWORD}@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: ${APP_SECRET}
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/heartbeat || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 5

  db:
    image: postgres:15-alpine
    container_name: umami-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
      interval: 5s
      timeout: 5s
      retries: 10

volumes:
  umami-db-data:

Genera los secretos. APP_SECRET firma las sesiones: si lo cambias más adelante, cierras todas las sesiones abiertas.

umask 077
cat > /opt/umami/.env <<EOF
DB_PASSWORD=$(openssl rand -base64 24)
APP_SECRET=$(openssl rand -hex 32)
EOF

docker compose up -d
docker compose logs -f umami

La primera arrancada ejecuta las migraciones de la base y tarda entre 30 y 60 segundos. Cuando curl http://127.0.0.1:3000/api/heartbeat responda, el servicio está vivo.

Igual que en la configuración de MinIO, el puerto se publica en 127.0.0.1. Umami no debe escucharse directamente en internet: Nginx se encarga de eso con TLS por delante.

Publicar con HTTPS y Nginx

Umami necesita un dominio propio con certificado válido porque el script de seguimiento se carga desde páginas que ya usan HTTPS. Un script en HTTP dentro de una página HTTPS lo bloquea el navegador por contenido mixto.

Crea el registro A analytics.ejemplo.com hacia la IP del VPS y configura Nginx:

server {
    listen 443 ssl;
    server_name analytics.ejemplo.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d analytics.ejemplo.com

X-Forwarded-For no es decorativo: Umami lo usa para deducir el país del visitante. Sin esa cabecera, todas las visitas aparecerán con la IP del proxy y la geolocalización quedará inservible.

Primer acceso y cuenta administrativa

Umami se instala con el usuario admin y la contraseña umami, y cambiarla es la primera tarea, no una recomendación. Cualquiera que conozca el proyecto probará ese par en tu dominio.

1. 1 Abre https://analytics.ejemplo.com.
2. 2 Entra con admin / umami.
3. 3 Ve a Settings → Profile y define una contraseña larga y única.
4. 4 Activa el segundo factor si tu versión lo ofrece.

Si el panel quedará expuesto solo a tu equipo, restringe el acceso por IP en Nginx o publícalo detrás de una VPN. La guía de instalar WireGuard en un VPS sirve para eso. Ojo con un detalle: el endpoint que recibe los datos (/api/send) debe seguir siendo público, porque lo llaman los navegadores de tus visitantes. Restringe el panel, no la recolección.

Añadir tu primer sitio y el script de seguimiento

Cada sitio recibe un ID único y su propio fragmento de código. En Settings → Websites → Add website introduce nombre y dominio. Umami genera algo así:

<script defer src="https://analytics.ejemplo.com/script.js"
        data-website-id="a1b2c3d4-0000-0000-0000-000000000000"></script>

Colócalo antes de </head>. En WordPress puedes usar un plugin de cabeceras o el archivo del tema hijo; en Astro, Next.js o Nuxt va en el layout principal.

Para verificar que mide, abre tu sitio en una ventana de incógnito y mira la pestaña Realtime. Si no aparece nada, revisa en la consola del navegador si el script cargó y si POST /api/send devuelve 200.

Los eventos personalizados no necesitan configuración previa: se declaran con un atributo en el elemento.

<button data-umami-event="cotizacion-enviada"
        data-umami-event-plan="vps-4gb">Solicitar cotización</button>

O desde JavaScript:

umami.track('descarga-pdf', { archivo: 'tarifario-2026.pdf' });

Regla práctica: no metas datos personales en las propiedades de un evento. Un correo o una cédula dentro de una propiedad convierte una herramienta sin datos personales en una base que sí los contiene, con las obligaciones que eso implica.

Cómo trata Umami la privacidad

Umami no escribe cookies y no guarda la IP del visitante en claro: construye un identificador de sesión con un hash de IP, agente de usuario y una sal que rota a diario. Al día siguiente, el mismo visitante ya no es reconocible como el mismo. Por eso el panel muestra visitas y sesiones, pero no puede seguir a una persona durante semanas.

Sobre la parte legal conviene ser preciso. La ausencia de cookies elimina la base técnica de muchos requisitos de consentimiento del GDPR, y alojar el servidor tú mismo evita transferencias internacionales de datos. Pero cumplir no es instalar un software: en Ecuador, la Ley Orgánica de Protección de Datos Personales tiene régimen sancionatorio vigente desde el 26 de mayo de 2023, y sigue exigiendo política de privacidad, base de licitud y registro de tratamientos. Umami te pone en una posición mucho más cómoda; no firma tu cumplimiento.

Varios sitios, usuarios y equipos

Una sola instancia sirve para todos los dominios que administres, con separación por usuario o por equipo. El flujo típico de una agencia es: crear un equipo por cliente, asignarle sus sitios y dar acceso de solo lectura a la persona de contacto. El cliente ve sus métricas y no ve las de nadie más.

Umami también permite compartir un enlace público de un sitio concreto, útil para un panel en pantalla o para un informe que no requiera credenciales. Revísalo antes de activarlo: un enlace compartido es accesible para quien lo tenga.

Backups, retención y actualizaciones

Todo el valor de Umami está en la base PostgreSQL; el contenedor de la aplicación es reemplazable. Un volcado diario comprimido resuelve el respaldo:

docker exec umami-db pg_dump -U umami umami | gzip > /var/backups/umami-$(date +%F).sql.gz

Programa el envío a otro servidor con cron y verifica la restauración en un entorno de prueba; la guía de backups con rsync y cron cubre el traslado fuera del VPS.

Para actualizar, respalda primero y luego descarga la nueva imagen:

cd /opt/umami
docker exec umami-db pg_dump -U umami umami | gzip > /var/backups/umami-pre-update.sql.gz
docker compose pull
docker compose up -d
docker compose logs --tail=100 umami

Las migraciones se aplican al arrancar. Si el contenedor entra en bucle de reinicio, el log dirá si falló una migración; no borres el volumen para "arreglarlo", porque ahí están todos tus datos históricos.

Vigila el tamaño de la base cada cierto tiempo:

docker exec umami-db psql -U umami -d umami -c \
  "SELECT pg_size_pretty(pg_database_size('umami'));"

Problemas frecuentes