Umami es una de las mejores alternativas privacy-focused y self-hosted para analíticas web. Sin embargo, un problema extremadamente común cuando lo desplegamos detrás de Cloudflare Tunnels es que el tablero identifica el país del visitante, pero los campos de Ciudad y Región aparecen vacíos (—).
En esta guía, veremos cómo solucionar este “cortocircuito” de telemetría configurando correctamente las cabeceras HTTP para que Cloudflare le entregue a Umami toda la información geográfica que necesita.
El Problema: El “Cortocircuito” de las Cabeceras
Cuando el tráfico pasa por Cloudflare, este inyecta por defecto una cabecera llamada CF-IPCountry (por ejemplo, con el valor MX o US).
La lógica interna de Umami dicta que si recibe información geográfica a través de las cabeceras HTTP, asumirá que esa información es la única fuente de la verdad e ignorará su base de datos local (MaxMind GeoDB). Como Cloudflare no envía la ciudad ni la región por defecto, Umami registra el país, busca la ciudad en las cabeceras, no la encuentra, y deja los campos vacíos.
Para solucionarlo, debemos hacer que Cloudflare envíe el paquete geográfico completo.
1. Configurar Cloudflare (Managed Transforms)
En lugar de depender de la base de datos local de Umami, vamos a aprovechar la telemetría masiva de la red Edge de Cloudflare para que nos resuelva la ubicación exacta y se la pase a nuestro contenedor.
- Inicia sesión en el panel de Cloudflare y selecciona tu dominio.
- En el menú lateral izquierdo, navega a Rules > Settings.
- Selecciona la pestaña Managed Transforms.
- Busca la opción Add visitor location headers y actívala.
Al encender esto, Cloudflare comenzará a inyectar las cabeceras CF-IPCity (Ciudad) y CF-RegionCode (Estado/Región) en todo el tráfico que fluya hacia tu túnel.
2. Configurar Umami (Docker Compose)
Ahora debemos asegurarnos de que Umami esté configurado para confiar en las IPs que provienen del proxy de Cloudflare. Edita tu archivo docker-compose.yml y añade la variable CLIENT_IP_HEADER.
services:
umami:
image: ghcr.io/umami-software/umami:postgresql-latest
container_name: umami_app
environment:
# Database connection string
DATABASE_URL: postgresql://umami_user:password@umami_db:5432/umami_data
DATABASE_TYPE: postgresql
APP_SECRET: your_random_secret
# Tell Umami to trust the real IP forwarded by Cloudflare
CLIENT_IP_HEADER: cf-connecting-ip
depends_on:
- umami_db
restart: unless-stopped
3. Aplicar Cambios y Verificar
Recrea tu contenedor para aplicar la nueva variable de entorno:
# Recreate the Umami container to apply the new environment variables
docker compose up -d
Realiza una visita de prueba a tu sitio web (preferiblemente desde una red móvil o modo incógnito). En el dashboard de Umami, ahora verás que la telemetría geográfica está completa.
Conclusión
Delegar la geolocalización a Cloudflare no solo soluciona el problema de los campos vacíos, sino que también optimiza tu instancia de Umami al no depender de una base de datos GeoIP local que requiere actualizaciones constantes. Con un par de clics en Cloudflare y una línea en Docker, tu analítica ahora es mucho más precisa.
End of transmission.