Alojar Umami en un VPS administrado: su analítica web en su propio servidor

Qué hace Umami

Umami es una plataforma de analítica web y de producto de código abierto. Su documentación describe una herramienta que reúne el tráfico, las campañas, el comportamiento de los visitantes, las conversiones, la retención y los ingresos, desde la primera visita hasta los resultados que cuentan para su actividad. Está escrita en TypeScript sobre Next.js, y su imagen Docker se ejecuta con una cuenta sin privilegios.

• La captación: páginas vistas, visitantes, sitios de procedencia, países, dispositivos y actividad en tiempo real, con campañas UTM, enlaces cortos y píxeles de seguimiento.
• El comportamiento: eventos personalizados, recorridos, grabaciones de sesiones, mapas de calor, segmentos, cohortes y retención.
• La conversión: objetivos, embudos, atribución y seguimiento de los ingresos por página y por campaña.
• El uso compartido: tableros, equipos, una URL pública para compartir, una API y un servidor MCP de solo lectura para su asistente de IA.
• Los sitios modernos: la FAQ indica que Umami sigue por sí solo la navegación entre páginas en las aplicaciones de una sola página, sin ningún ajuste adicional.

Una sola instancia sigue varios sitios web: cada uno recibe su propio identificador y su script de seguimiento, y sus colegas se organizan mediante cuentas y equipos.

Lo que permite la licencia MIT

Umami se publica bajo la licencia MIT, a nombre de Umami Software, Inc. Concede, de forma gratuita, el derecho a usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y vender copias del software. Puede, por tanto, ejecutarlo para su empresa y para los sitios de sus clientes, sin ninguna licencia que comprar.

Su única condición: el aviso de copyright y el aviso de permiso acompañan a todas las copias o partes sustanciales del software. Como cualquier licencia MIT, ofrece el software «tal cual», sin garantía.

Las cookies y los datos personales: lo que dice el proyecto

La documentación presenta Umami como una analítica sin cookies, sin seguimiento entre sitios y sin recogida automática de datos personales. Autoalojado, guarda su analítica en su propio servidor: usted decide dónde se guarda y cuánto tiempo se conserva.

Tres ajustes del script de seguimiento van más allá, si lo desea: data-exclude-search retira los parámetros de búsqueda de las URL registradas, data-exclude-hash retira el fragmento, y data-do-not-track desactiva el seguimiento en los navegadores que expresan la preferencia Do Not Track. La documentación señala que este último ajuste no constituye, por sí solo, una solución completa de gestión del consentimiento.

Si identifica a los visitantes conectados con data-distinct-id o umami.identify(), la documentación recomienda un identificador interno de usuario o un hash en lugar de una dirección de correo: el valor puede leerse en el HTML de la página.

La instalación con Docker Compose y PostgreSQL

El repositorio ofrece un docker-compose.yml que arranca Umami y su base de datos PostgreSQL. Desde la versión 3, PostgreSQL es la única base admitida, en la versión 12.14 como mínimo, y la documentación recomienda configurarla en la zona horaria UTC. En un servidor con Docker instalado, cree una carpeta y empiece por sus secretos, generados al azar con openssl, como sugiere la documentación:

cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
APP_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

Coloque después este compose.yaml a su lado. Sigue el archivo del proyecto en la versión 3.4.1, con dos cambios: los secretos proceden del archivo .env, y el puerto solo se publica en 127.0.0.1.

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

docker compose up -d
curl -s http://127.0.0.1:3000/api/heartbeat

• DATABASE_URL: la única variable obligatoria, la cadena de conexión a la base. La contraseña hexadecimal se escribe tal cual; una contraseña con caracteres especiales necesitaría codificación porcentual.
• APP_SECRET: una cadena aleatoria que protege los tokens de autenticación, única para cada instalación. En el código de la versión 3.4.1, interviene también en el cálculo de los identificadores de sesión: manténgala estable.
• TWO_FACTOR_ENCRYPTION_KEY: 64 caracteres hexadecimales que cifran los secretos de la doble autenticación. Sin ella, nadie puede activar la doble autenticación.
• Al arrancar, el contenedor comprueba la conexión y la versión de la base, y aplica él mismo las migraciones del esquema. En el primer arranque, crea las tablas y la cuenta admin. La sonda /api/heartbeat responde {"ok":true} en cuanto Umami está listo.
• La etiqueta latest sigue la última versión publicada. El registro del proyecto publica también etiquetas de versión, como 3.4.1, para fijar la que ejecuta.

La documentación de instalación no da ninguna cifra de memoria ni de procesador. El tamaño depende del tráfico de los sitios seguidos y del volumen de datos que conserve. En un VPS administrado, descríbanos su uso y le recomendamos el tamaño adecuado.

HTTPS: el proxy inverso

Umami escucha en HTTP en el puerto 3000, y la documentación sugiere servirlo detrás de su servidor web, mediante un proxy inverso. Dele su propio subdominio, como stats.example.com, que apunte al servidor con registros A y AAAA. Servir Umami bajo una ruta pasa por BASE_PATH, una variable que se lee al compilar la aplicación: con la imagen publicada, el subdominio es la vía directa.

El proxy debe transmitir también la dirección del visitante. Umami la lee en las cabeceras que recibe, entre ellas X-Real-IP y X-Forwarded-For: la usa para distinguir a los visitantes y localizar su país. Si su proxy usa otra cabecera, CLIENT_IP_HEADER la indica.

Con Caddy

Caddy obtiene el certificado de Let’s Encrypt y activa HTTPS por sí mismo. Su directiva reverse_proxy establece X-Forwarded-For por defecto: estas tres líneas bastan.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Con Nginx y Certbot

Este bloque sigue el ejemplo de Nginx de la documentación de Umami, y escucha en el puerto 80 para que Certbot pueda instalar HTTPS:

server {
  listen 80;
  listen [::]:80;
  server_name stats.example.com;

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

Certbot instala después el certificado y se encarga de renovarlo:

sudo certbot --nginx

El primer inicio de sesión: la cuenta admin y la doble autenticación

Al crear su base de datos, Umami abre una cuenta de administrador: usuario admin, contraseña umami. La documentación pide cambiar esta contraseña en el primer inicio de sesión.

1. Abra su dirección HTTPS e inicie sesión con admin y umami.
2. Abra Settings desde el botón de perfil de la barra lateral, después Profile, y haga clic en Change password.
3. En la pestaña Security, active la doble autenticación: escanee el código QR con su aplicación de autenticación, introduzca el código de seis cifras y guarde después en lugar seguro los diez códigos de respaldo, que solo se muestran una vez.

• Exigir la doble autenticación: un administrador puede exigirla para toda la instancia, para un usuario o para un equipo, desde las páginas de administración.
• Los intentos: cinco códigos erróneos bloquean los intentos siguientes durante 15 minutos.
• Las cuentas de su equipo: las páginas de administración gestionan los usuarios, los sitios y los equipos de toda la instancia.

Guarde TWO_FACTOR_ENCRYPTION_KEY con sus copias de seguridad: la documentación advierte de que perder o cambiar esta clave hace ilegibles los secretos guardados, y cada usuario debe entonces volver a configurar la doble autenticación.

Añadir un sitio y su script de seguimiento

1. En Websites, haga clic en Add website.
2. Dé un nombre al sitio y después su dominio: Umami lo usa para excluir sus propias páginas de la lista de sitios de procedencia.
3. Abra Edit en ese sitio y copie el código de la sección Tracking code.
4. Péguelo en el <head> de sus páginas y visite después su sitio: los datos aparecen enseguida en el panel.

<script defer src="https://stats.example.com/script.js" data-website-id="your-website-id"></script>

• ¿No aparece nada? La documentación sugiere la pestaña de red de las herramientas de desarrollo del navegador: las peticiones hacia su instancia deben salir sin errores.
• Next.js: añada el código con el componente next/script en lugar de una simple etiqueta <script>.
• data-domains limita el seguimiento a sus dominios de producción, lo que deja sus entornos de prueba fuera de las estadísticas.
• Sus propias visitas se excluyen sitio por sitio, desde la consola del navegador, con localStorage.setItem('umami.disabled', 1).

Un nombre de script propio

Algunos bloqueadores de anuncios bloquean todo lo que parece analítica. Autoalojado, Umami ya se sirve desde su propio dominio, y dos variables van más allá: TRACKER_SCRIPT_NAME da al script un nombre distinto de script.js, y COLLECT_API_ENDPOINT cambia el nombre del punto de recogida, en lugar de /api/send. El script llama entonces por sí mismo al nuevo punto; en sus páginas solo cambia la fuente del código de seguimiento.

TRACKER_SCRIPT_NAME: "stats.js"
COLLECT_API_ENDPOINT: "/api/collect"

Los ajustes útiles

Estas variables de entorno van en el servicio umami de compose.yaml, y docker compose up -d recrea después el contenedor para tenerlas en cuenta:

Las copias de seguridad

Todo lo que Umami conserva vive en su base de datos PostgreSQL: cuentas, sitios, equipos y analítica. Expórtela cada día y justo antes de cada actualización: autoalojados, estos datos se conservan sin límite de tiempo. Junto a la base, el archivo .env guarda los secretos que la hacen utilizable:

Exportar la base en funcionamiento

pg_dump hace una exportación coherente mientras la base está en uso. El formato personalizado, -Fc, va comprimido y se restaura con pg_restore:

docker compose exec -T db pg_dump -U umami -d umami -Fc > umami-$(date +%F).dump

Programe este comando en el servidor al menos una vez al día, haga limpieza entre las exportaciones, que se acumulan, y envíe una copia a otro lugar. Colocadas en el disco del servidor, estas exportaciones entran también en sus copias de seguridad nocturnas.

Restaurar

1. Detenga Umami y deje la base en marcha: docker compose stop umami.
2. Restaure la exportación en la base, sustituyendo los objetos existentes.
3. Vuelva a arrancar Umami y compruebe después que sus sitios y su analítica están ahí.

docker compose stop umami
docker compose exec -T db pg_restore -U umami -d umami --clean --if-exists < umami-YYYY-MM-DD.dump
docker compose start umami

Repita este ejercicio de vez en cuando, sobre una copia: así comprueba que una copia de seguridad funciona.

Las actualizaciones

La documentación da dos comandos, desde la carpeta del compose.yaml. La base de datos se queda en su volumen:

docker compose pull
docker compose up --force-recreate -d

Al reiniciar, el contenedor aplica por sí mismo las migraciones del esquema. La versión 3.4.0, del 17 de septiembre de 2026, traía dos, para las anotaciones y las claves de API; la versión 3.4.1, del 23 de octubre de 2026, no trae ninguna. Tras una actualización mayor, como el paso a la versión 3, la documentación sugiere ejecutar ANALYZE en PostgreSQL para que los paneles recuperen su velocidad:

docker compose exec db psql -U umami -d umami -c "ANALYZE;"

• Las notas de versión indican lo que cambia cada versión. La 3.4.1 es una corrección urgente de seguridad que actualiza Next.js y la imagen base de Node.js; sus notas piden a todas las instancias autoalojadas que actualicen descargando de nuevo la imagen.
• Desde una versión 2 con MySQL: la versión 3 ya no admite MySQL. La guía de migración del proyecto traslada los datos a PostgreSQL en la versión 2.19.0, antes de pasar a la versión 3.
• El propio PostgreSQL: conserve la etiqueta postgres:15-alpine del archivo. Pasar a una nueva versión mayor de PostgreSQL exige una exportación y una restauración, o pg_upgrade.

Quién hace qué en un VPS administrado

El autoalojamiento exige mantener el servidor además de la aplicación. En un VPS administrado, nuestros equipos se encargan del servidor y siguen su instancia de forma proactiva; Umami sigue siendo su software, con sus ajustes y sus datos.

Si prefiere que nuestros equipos intervengan en la propia aplicación, ese servicio se factura por horas o a precio cerrado, con un presupuesto comunicado antes de la intervención.