Instalación y configuración de Umami

1. Qué estamos configurando y por qué

Para 2026, el panorama de la analítica web ha experimentado cambios significativos. El endurecimiento de la legislación sobre protección de datos (GDPR en Europa, CCPA en EE. UU. y leyes similares en otras regiones) ha hecho que el uso de Google Analytics 4 (GA4) sea un proceso complejo y a menudo arriesgado. Las constantes notificaciones de cookies molestan a los usuarios y reducen la conversión. Aquí es donde entra en escena Umami Analytics.

Umami es una solución de código abierto que recopila solo las métricas necesarias (vistas, fuentes, dispositivos, países, eventos) sin recopilar información de identificación personal (PII). Esto permite prescindir legalmente de los molestos banners de cookies, ya que el servicio no rastrea a los usuarios entre sitios ni crea su perfil digital para redes publicitarias.

Qué obtendrá al final:

• Su propio panel de analítica en su dominio (por ejemplo, stats.sudominio.com).
• Control total sobre la base de datos: nadie más que usted tiene acceso a las estadísticas.
• Alta velocidad de funcionamiento: Umami está escrito en Next.js y optimizado para el procesamiento rápido de millones de eventos.
• Posibilidad de eludir los bloqueadores de anuncios (AdBlock), ya que el script se carga desde su propio subdominio.

Elegir una solución self-hosted basada en VPS es la única forma de garantizar el 100% de la soberanía de los datos. Las versiones en la nube de Umami son convenientes, pero vuelven a plantear la cuestión de confiar los datos a un tercero. Un servidor propio resuelve esta cuestión de una vez por todas.

2. Qué configuración de VPS se necesita para esta tarea

Umami Analytics es extremadamente poco exigente con los recursos en la etapa inicial, pero sus necesidades crecen junto con el volumen de tráfico de sus proyectos. La carga principal recae en la base de datos PostgreSQL al realizar consultas analíticas por períodos prolongados.

Para un funcionamiento estable del sistema, especialmente si planea rastrear varios sitios, lo mejor es adquirir un VPS con 2 GB de memoria RAM. Esto proporcionará suficiente caché para PostgreSQL y evitará que se active el OOM Killer (Out of Memory) al generar informes complejos.

¿Cuándo vale la pena considerar un servidor dedicado? Si su tráfico supera los 10-15 millones de eventos al mes, o si utiliza Umami como parte de un centro analítico para decenas de clientes importantes. En los demás casos, la virtualización (KVM) es más que suficiente.

Ubicación: Elija la ubicación del servidor lo más cerca posible de su audiencia principal. A pesar de que el script de Umami es asíncrono, una transmisión rápida de paquetes (baja latencia) reduce la probabilidad de pérdida de datos cuando un usuario abandona la página antes de que se complete la solicitud de analítica.

3. Preparación del servidor

Antes de proceder con la instalación de Umami, es necesario garantizar la seguridad y la actualidad de nuestro entorno. Utilizaremos Ubuntu 26.04 LTS (o la versión 24.04 actual en este momento).

En primer lugar, actualizaremos la lista de paquetes y el sistema en sí:

sudo apt update && sudo apt upgrade -y

Crearemos un usuario independiente con privilegios sudo para no trabajar como root:

# Создаем пользователя
adduser umamiadmin
# Добавляем в группу sudo
usermod -aG sudo umamiadmin
# Переключаемся на пользователя
su - umamiadmin
    

Configuraremos el firewall básico (UFW). Necesitaremos los puertos 22 (SSH), 80 (HTTP) y 443 (HTTPS):

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
    

Para protegerse contra ataques de fuerza bruta, instalaremos fail2ban:

sudo apt install fail2ban -y

La configuración básica de fail2ban ya protege el SSH de fábrica, lo cual es fundamental para cualquier VPS público.

4. Instalación de Docker y software auxiliar

En 2026, Docker sigue siendo el estándar de facto para el despliegue de aplicaciones self-hosted. Esto aísla las dependencias de Umami de las bibliotecas del sistema y simplifica el proceso de actualización.

Instalaremos los paquetes necesarios para trabajar con repositorios a través de HTTPS:

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

Añadiremos la clave GPG oficial de Docker:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
    

Conectaremos el repositorio:

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/apt/sources.list.d/docker.list > /dev/null
    

Instalaremos Docker Engine y Docker Compose:

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

Añadiremos a nuestro usuario al grupo docker para ejecutar contenedores sin sudo:

sudo usermod -aG docker $USER

Atención: Para que los cambios surtan efecto, debe cerrar la sesión y volver a entrar (logout/login).

5. Despliegue de Umami Analytics mediante Docker Compose

Utilizaremos la imagen oficial de Umami y la base de datos PostgreSQL 18. Esta es la combinación más estable y eficiente.

Crearemos un directorio de trabajo:

mkdir ~/umami && cd ~/umami

Crearemos el archivo docker-compose.yml. Utilizaremos una sintaxis moderna:

nano docker-compose.yml

Inserte el siguiente contenido:

services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    restart: always
    environment:
      DATABASE_URL: postgresql://umami_user:strong_password@db:5432/umami_db
      APP_SECRET: $(openssl rand -base64 32)
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy
    networks:
      - umami-net

  db:
    image: postgres:18-alpine
    restart: always
    environment:
      POSTGRES_USER: umami_user
      POSTGRES_PASSWORD: strong_password
      POSTGRES_DB: umami_db
    volumes:
      - ./sql_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami_user -d umami_db"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - umami-net

networks:
  umami-net:
    driver: bridge
    

Importante: Reemplace strong_password por una contraseña realmente compleja. El parámetro APP_SECRET se utiliza para cifrar las sesiones; puede generarlo con el comando openssl rand -base64 32 e insertarlo manualmente en lugar de la variable.

Ahora iniciaremos nuestra infraestructura:

docker compose up -d

Comprobaremos el estado de los contenedores:

docker compose ps

Si en la columna STATUS aparece "Up (healthy)", significa que la base de datos está lista y la aplicación se está ejecutando en el puerto 3000.

6. Configuración de Reverse Proxy (Nginx) y SSL (Certbot)

Ejecutar Umami directamente en el puerto 3000 en el internet abierto es una mala práctica. Necesitamos Nginx como proxy inverso para manejar los certificados SSL y garantizar la seguridad.

Instalemos Nginx:

sudo apt install nginx -y

Crearemos un archivo de configuración para nuestro dominio (por ejemplo, stats.example.com):

sudo nano /etc/nginx/sites-available/umami

Añada la siguiente configuración:

server {
    listen 80;
    server_name stats.example.com; # Замените на ваш домен

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

Activemos la configuración y reiniciemos Nginx:

sudo ln -s /etc/nginx/sites-available/umami /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
    

Ahora protejamos la conexión con Let's Encrypt:

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d stats.example.com
    

Certbot cambiará automáticamente la configuración de Nginx, añadirá los certificados SSL y configurará el redireccionamiento de HTTP a HTTPS.

7. Ajuste fino e integración del rastreador

Después de la instalación, vaya a la dirección https://stats.example.com. Datos para el primer inicio de sesión por defecto:

• Username: admin
• Password: umami

¡Lo primero que debe hacer es cambiar la contraseña del administrador en la configuración del perfil!

Añadir un sitio web

1. Vaya a la sección Settings -> Websites.
2. Haga clic en Add Website.
3. Ingrese el nombre y el dominio de su sitio.
4. Haga clic en Save.

Después de guardar, verá el botón Get tracking code. El código se verá aproximadamente así:

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

Este script debe insertarse en la sección <head> de su sitio. Tenga en cuenta el atributo async; garantiza que la carga de las analíticas no bloquee la renderización del contenido principal de la página.

Evadir bloqueadores (Pro-tip)

Muchos bloqueadores de anuncios buscan la palabra "script.js" o peticiones a dominios con la palabra "stats". En la configuración de Umami en Docker Compose, puede cambiar el nombre del script a través de una variable de entorno:

TRACKER_SCRIPT_NAME: custom-analytics

Después de esto, su script estará disponible en la dirección /custom-analytics.js, lo que aumentará significativamente la precisión de la recopilación de datos entre la audiencia técnicamente avanzada.

8. Copias de seguridad y mantenimiento

Los datos de analítica se acumulan y su pérdida puede ser dolorosa. El elemento más importante para la copia de seguridad es la base de datos PostgreSQL.

Crearemos un script sencillo para la copia de seguridad diaria:

mkdir ~/backups && nano ~/backups/backup.sh

#!/bin/bash
# Настройки
BACKUP_DIR="$HOME/backups/data"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
CONTAINER_NAME="umami-db-1" # Проверьте имя через docker ps
DB_USER="umami_user"
DB_NAME="umami_db"

# Создаем папку если нет
mkdir -p $BACKUP_DIR

# Делаем дамп
docker exec $CONTAINER_NAME pg_dump -U $DB_USER $DB_NAME > $BACKUP_DIR/umami_backup_$TIMESTAMP.sql

# Удаляем бэкапы старше 30 дней
find $BACKUP_DIR -type f -mtime +30 -name ".sql" -delete
    

chmod +x ~/backups/backup.sh
crontab -e
# Добавьте строку для запуска в 3 часа ночи ежедневно:
0 3    /home/umamiadmin/backups/backup.sh
    

Actualización de Umami: Gracias a Docker, la actualización a la última versión se realiza en tres comandos:

cd ~/umami
docker compose pull
docker compose up -d
    

Umami realizará automáticamente las migraciones de la base de datos al iniciar la nueva versión.

9. Solución de problemas + FAQ

Error "Database connection failed" al iniciar

Con mayor frecuencia, esto sucede cuando el contenedor de Umami intenta conectarse a la base de datos antes de que PostgreSQL se haya inicializado por completo. En nuestro docker-compose.yml, añadimos un healthcheck que resuelve este problema. Si el error persiste, verifique la corrección de DATABASE_URL y la coincidencia de las contraseñas en ambos servicios.

El script de analítica no se carga (404 Not Found)

Verifique la configuración de Nginx. Asegúrese de que proxy_pass apunte al puerto correcto (3000). También asegúrese de no estar utilizando Cloudflare en modo "Under Attack Mode", que puede bloquear las peticiones JS a nuevos subdominios.

¿Qué configuración de VPS es el mínimo adecuado?

Para un blog pequeño con un tráfico de hasta 500 personas al día, es suficiente con 1 vCPU y 1 GB de RAM. Sin embargo, para un funcionamiento fluido del panel de control (dashboard), que genera gráficos "al vuelo", recomendamos 2 GB de RAM. Esto permitirá que la base de datos PostgreSQL mantenga los índices en memoria.

¿Qué elegir: VPS o dedicado para esta tarea?

En el 95% de los casos, un VPS es la mejor opción. Permite escalar fácilmente los recursos (CPU/RAM) a medida que crece su proyecto. Un servidor dedicado (dedicated) solo tiene sentido si está agregando datos de cientos de sitios de alta carga y se ve limitado por el rendimiento del subsistema de disco (I/O) o si requiere configuraciones de seguridad específicas a nivel de hardware.

¿Cómo transferir datos desde Google Analytics?

En este momento, la importación directa del historial de GA4 a Umami es difícil debido a la diferente estructura de datos. La mayoría de los usuarios comienzan la recopilación "desde cero", ejecutando ambos contadores en paralelo durante un período de transición de 1 a 2 meses.

¿Afecta Umami al SEO?

Sí, positivamente. Dado que el script de Umami pesa entre 20 y 30 veces menos que el pesado paquete de Google Analytics, los indicadores de Core Web Vitals (especialmente LCP y TBT) mejoran. Los sitios rápidos posicionan mejor.

10. Conclusiones y próximos pasos

Hemos desplegado con éxito su propio sistema de analítica, que le pertenece por completo. Ya no depende de los caprichos de las corporaciones, no teme el bloqueo de cuentas y garantiza a sus usuarios el máximo nivel de privacidad.

Qué hacer a continuación:

• Configure eventos (Events): En Umami puede rastrear clics en botones, envíos de formularios y descargas de archivos. Esto se hace a través de simples atributos data-umami-event en HTML.
• Configure notificaciones: Integre alertas (a través de scripts personalizados) si el tráfico en el sitio cae o aumenta drásticamente.
• Optimice PostgreSQL: Al alcanzar millones de registros, vale la pena estudiar el ajuste de los parámetros shared_buffers y work_mem en la configuración de la base de datos para acelerar los informes pesados.

Self-hosting es el camino hacia la libertad en el espacio digital. Con un VPS correctamente configurado y software moderno como Umami, está creando una base sólida para sus proyectos.