Pi-hole Docker Compose: Bloquea Anuncios en Toda tu Red 2025

Pi-hole Docker Compose es la solución definitiva para bloquear anuncios y rastreadores en toda tu red doméstica sin instalar software en cada dispositivo. En esta guía completa sobre pi-hole docker compose, aprenderás a desplegar este potente sistema de manera profesional, configurar protección DNS avanzada, y proteger todos tus dispositivos 24/7 incluyendo móviles, tablets, smart TVs y dispositivos IoT.

Si estás cansado de ver anuncios invasivos en tus aplicaciones móviles, smart TV o dispositivos que no permiten instalar bloqueadores tradicionales, implementar pi-hole docker compose es tu respuesta. Con más de 54.500 estrellas en GitHub y una comunidad activa de millones de usuarios, se ha convertido en el estándar de facto para bloqueo de anuncios a nivel de red.

¿Qué es Pi-hole?

Pi-hole es un servidor DNS que actúa como «agujero negro» para publicidad y rastreadores web. A diferencia de los bloqueadores tradicionales que funcionan solo en navegadores, Pi-hole intercepta las peticiones DNS de TODOS los dispositivos conectados a tu red antes de que lleguen a internet.

Cuando un dispositivo intenta cargar un anuncio o contactar con un rastreador, Pi-hole consulta sus listas de bloqueo (que contienen millones de dominios maliciosos y publicitarios) y simplemente devuelve una respuesta vacía. El resultado con pi-hole docker compose: anuncios bloqueados, navegación más rápida y mayor privacidad en todos tus dispositivos.

Características Principales

• Bloqueo a nivel DNS: Protege toda tu red sin configurar cada dispositivo individualmente
• Dashboard web intuitivo: Interfaz visual con estadísticas en tiempo real de consultas bloqueadas
• Listas de bloqueo actualizables: Millones de dominios maliciosos actualizados constantemente
• Servidor DHCP integrado: Opcionalmente puede gestionar las IPs de tu red
• Caché DNS: Acelera la navegación almacenando consultas frecuentes
• Soporte IPv4 e IPv6: Protección completa en ambos protocolos
• API REST: Integración con herramientas de automatización y monitorización
• Logs detallados: Auditoría completa de todas las peticiones DNS

Casos de Uso Reales

1. Hogar inteligente: Bloquea telemetría de smart TVs, asistentes de voz y dispositivos IoT
2. Protección infantil: Filtra contenido inapropiado a nivel de red sin apps adicionales
3. Seguridad empresarial: Protege redes pequeñas contra phishing y malware
4. Privacidad mejorada: Bloquea rastreadores de Google, Facebook y redes publicitarias
5. Aceleración de red: Reduce ancho de banda bloqueando contenido no deseado

Arquitectura de Pi-hole Docker Compose

La arquitectura de pi-hole docker compose se basa en un contenedor principal que ejecuta múltiples servicios integrados:

• FTL (Faster Than Light): Motor DNS optimizado escrito en C
• dnsmasq: Servidor DNS y DHCP ligero
• lighttpd: Servidor web para el dashboard administrativo
• PHP: Backend para la interfaz web y API
• Gravity: Motor de listas de bloqueo y actualizaciones

Cuando despliegas pi-hole docker compose, el flujo de consultas DNS funciona así:

1. Dispositivo solicita resolver un dominio (ej: ads.google.com)
2. Consulta llega al puerto 53 del contenedor pi-hole docker compose
3. FTL verifica si el dominio está en las listas de bloqueo
4. Si está bloqueado: devuelve 0.0.0.0 (null)
5. Si está permitido: reenvía consulta a DNS upstream (Cloudflare, Google)
6. Respuesta se cachea para acelerar futuras peticiones

Ventajas de Usar Pi-hole Docker Compose

Elegir pi-hole docker compose ofrece ventajas significativas sobre la instalación tradicional de Pi-hole:

• Portabilidad total: Mueve tu configuración entre servidores con un solo comando
• Actualizaciones simples: Cambiar de versión es tan fácil como docker compose pull && docker compose up -d
• Aislamiento completo: Pi-hole no interfiere con otros servicios del sistema
• Rollback instantáneo: Vuelve a versiones anteriores en segundos si algo falla
• Recursos predecibles: Controla exactamente cuánta CPU y RAM puede usar
• Backup sencillo: Solo necesitas respaldar la carpeta de configuración

Requisitos Previos

Antes de comenzar con la instalación de pi-hole docker compose, asegúrate de cumplir estos requisitos mínimos:

Hardware Mínimo

• CPU: 1 core (recomendado 2 cores para redes con +20 dispositivos)
• RAM: 512 MB mínimo, 1 GB recomendado
• Almacenamiento: 2 GB para contenedor + logs
• Red: Conexión estable, IP estática recomendada

Software Necesario

• Docker: Versión 20.10 o superior
• Docker Compose: Versión 2.0 o superior (comando docker compose)
• Sistema operativo: Linux (Ubuntu 22.04/24.04, Debian 11/12, Raspberry Pi OS)
• Acceso root: Para bind del puerto 53 (DNS)

Verifica tus versiones instaladas:

docker --version
docker compose version

Preparación del Sistema

El puerto 53 debe estar libre. En sistemas con systemd-resolved activo, desactívalo:

sudo systemctl disable systemd-resolved
sudo systemctl stop systemd-resolved
sudo rm /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf

Instalar Pi-hole Docker Compose Paso a Paso

Sigue esta guía paso a paso para configurar pi-hole docker compose desde cero en tu servidor:

Paso 1: Crear Estructura de Directorios

Crea un directorio dedicado para almacenar la configuración persistente de pi-hole docker compose:

mkdir -p ~/pi-hole/etc-pihole
mkdir -p ~/pi-hole/etc-dnsmasq.d
cd ~/pi-hole

Paso 2: Crear el Archivo docker-compose.yml

Crea el archivo de configuración pi-hole docker compose con este contenido optimizado para producción:

version: '3.8'

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    hostname: pihole

    ports:
      # DNS Ports
      - "53:53/tcp"
      - "53:53/udp"
      # Web Interface
      - "80:80/tcp"
      - "443:443/tcp"

    environment:
      # Zona horaria (ajusta según tu ubicación)
      TZ: 'Europe/Madrid'

      # Contraseña del panel web (¡CÁMBIALA!)
      FTLCONF_webserver_api_password: 'TuContraseñaSegura123!'

      # Modo de escucha en bridge network
      FTLCONF_dns_listeningMode: 'all'

      # Servidores DNS upstream (Cloudflare + Google)
      FTLCONF_dns_upstreams: '1.1.1.1;8.8.8.8'

      # Desactivar logs en stdout (opcional)
      TAIL_FTL_LOG: '0'

      # Habilitar IPv6 (opcional)
      FTLCONF_dns_ipv6: 'true'

    volumes:
      # Persistencia de configuración
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'

    cap_add:
      # Capacidades necesarias para DNS y DHCP
      - NET_ADMIN
      - SYS_TIME
      - SYS_NICE

    restart: unless-stopped

    # Límites de recursos (opcional pero recomendado)
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Variables de entorno importantes para pi-hole docker compose:

• TZ: Zona horaria para rotación correcta de logs
• FTLCONF_webserver_api_password: Contraseña de acceso al dashboard
• FTLCONF_dns_listeningMode: Debe ser ‘all’ para Docker bridge network
• FTLCONF_dns_upstreams: DNS upstream separados por punto y coma

Paso 3: Lanzar el Contenedor

Ejecuta el stack de Pi-hole:

docker compose up -d

Verifica que tu instalación de Pi-hole está ejecutándose correctamente:

docker compose ps
docker logs pihole

La salida debe mostrar algo similar a:

[✓] DNS service is running
[✓] Pi-hole blocking is enabled

Paso 4: Acceder al Panel de Administración

Abre tu navegador y accede al dashboard de tu instalación de Pi-hole:

http://TU_IP_SERVIDOR/admin/

Inicia sesión con la contraseña que configuraste en FTLCONF_webserver_api_password.

Paso 5: Configurar Dispositivos para Usar Pi-hole

Tienes dos opciones para que tus dispositivos usen tu servidor Pi-hole como DNS:

Opción A: Configurar a nivel de router (recomendado)

1. Accede al panel de administración de tu router
2. Busca la sección «DHCP» o «LAN Settings»
3. Cambia el DNS primario a la IP de tu servidor Pi-hole
4. DNS secundario: 1.1.1.1 (opcional, como respaldo)
5. Guarda cambios y reinicia el router

Opción B: Configurar manualmente en cada dispositivo

En Windows, Linux o macOS, configura el DNS en los ajustes de red con la IP de tu instalación de Pi-hole.

Configurar Pi-hole Docker Compose con Listas de Bloqueo Avanzadas

Tu stack pi-hole docker compose incluye listas de bloqueo predeterminadas, pero puedes añadir listas adicionales especializadas:

Añadir Listas Personalizadas

1. Accede al panel web de Pi-hole → Adlists
2. Añade estas listas recomendadas:

# Bloqueo agresivo de publicidad
https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts

# Protección contra malware
https://malware-filter.gitlab.io/malware-filter/urlhaus-filter-hosts.txt

# Bloqueo de rastreadores
https://hostfiles.frogeye.fr/firstparty-trackers-hosts.txt

# Telemetría de Windows
https://raw.githubusercontent.com/crazy-max/WindowsSpyBlocker/master/data/hosts/spy.txt

3. Haz clic en «Update Gravity» para aplicar los cambios

Configurar Whitelist para Servicios Legítimos

Algunos servicios pueden bloquearse incorrectamente en pi-hole docker compose. Añádelos a la whitelist:

# Desde el panel web: Whitelist → Add domain
# O desde línea de comandos:
docker exec pihole pihole -w www.ejemplo.com

Dominios comunes que suelen necesitar whitelist:

• s.shopify.com – Tiendas Shopify
• www.googleadservices.com – Google Shopping
• clientservices.googleapis.com – Chrome sync
• tracking.epicgames.com – Epic Games Store

Optimización y Mejores Prácticas

Seguridad

1. Contraseña robusta

Genera una contraseña segura para el panel de administración de Pi-hole:

openssl rand -base64 32

2. Acceso HTTPS con proxy reverso

Combina pi-hole docker compose con Nginx Proxy Manager para acceso seguro vía HTTPS. Configura un subdominio como pihole.tudominio.com apuntando al puerto 80 del contenedor.

3. Firewall

Bloquea acceso externo al puerto 80 de Pi-hole si solo lo usarás en tu red local:

sudo ufw allow from 192.168.1.0/24 to any port 80
sudo ufw allow 53

Rendimiento

1. Ajustar tamaño de caché DNS

Crea el archivo ./etc-dnsmasq.d/99-custom.conf para optimizar tu instalación de Pi-hole:

cache-size=10000
log-queries=off

Reinicia el contenedor para aplicar cambios:

docker compose restart

2. Limpieza periódica de logs

Automatiza la limpieza de logs antiguos en pi-hole docker compose para evitar que crezcan indefinidamente:

# Añade a crontab:
0 3 * * 0 docker exec pihole pihole flush

Backups

Crea un script de backup automático para tu configuración pi-hole docker compose en ~/backup-pihole.sh:

#!/bin/bash
BACKUP_DIR="/backups/pihole"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/pihole_$DATE.tar.gz ~/pi-hole/etc-pihole

# Mantener solo últimos 7 backups
find $BACKUP_DIR -name "pihole_*.tar.gz" -mtime +7 -delete

Hazlo ejecutable y programa su ejecución:

chmod +x ~/backup-pihole.sh
# Añade a crontab para ejecutar diariamente:
0 2 * * * /home/usuario/backup-pihole.sh

Troubleshooting Pi-hole Docker Compose

Error: «Port 53 already in use»

Causa: Otro servicio (generalmente systemd-resolved) está usando el puerto 53 necesario para pi-hole docker compose.

Solución:

# Verificar qué proceso usa el puerto 53:
sudo lsof -i :53

# Si es systemd-resolved:
sudo systemctl disable systemd-resolved
sudo systemctl stop systemd-resolved

# Reintenta el despliegue:
docker compose up -d

El Dashboard No Carga

Causa: Problema de permisos en volúmenes de Pi-hole o puerto 80 ocupado.

Solución:

# Verifica logs del contenedor:
docker logs pihole

# Verifica permisos:
sudo chown -R 999:999 ~/pi-hole/etc-pihole

# Si puerto 80 está ocupado, cámbialo en docker-compose.yml:
ports:
  - "8080:80/tcp"  # Accede via http://IP:8080/admin/

Resolución DNS Muy Lenta

Causa: Servidores DNS upstream lentos o listas de bloqueo excesivas en tu stack de Pi-hole.

Solución:

# Prueba con DNS upstream más rápidos (Cloudflare):
# Edita docker-compose.yml y cambia:
FTLCONF_dns_upstreams: '1.1.1.1;1.0.0.1'

# Reduce el número de listas activas en Adlists
# Verifica latencia de DNS upstream:
docker exec pihole dig @1.1.1.1 google.com

Algunos Sitios Se Bloquean Por Error

Causa: Falsos positivos en listas de bloqueo muy agresivas de Pi-hole.

Solución:

# Consulta el query log en el dashboard para identificar el dominio bloqueado
# Añádelo a whitelist temporalmente:
docker exec pihole pihole -w dominio-bloqueado.com

# O permanentemente desde el panel web: Whitelist → Add

Pi-hole No Se Reinicia Tras Actualización

Causa: Cambios incompatibles en nueva versión de Pi-hole (especialmente v5 → v6).

Solución:

# Verifica logs de error:
docker logs pihole --tail 100

# Si hay error de migración, backup y limpia volúmenes:
docker compose down
cp -r ~/pi-hole/etc-pihole ~/pi-hole/etc-pihole.backup
sudo rm -rf ~/pi-hole/etc-pihole/*
docker compose up -d

# Restaura configuración manualmente desde el backup

Integración Pi-hole Docker Compose con Otros Servicios

Combinar con Unbound para DNS Recursivo

Unbound te permite ser tu propio servidor DNS recursivo para máxima privacidad con Pi-hole. Añade este servicio a tu docker-compose.yml:

  unbound:
    container_name: unbound
    image: mvance/unbound:latest
    ports:
      - "5335:53/tcp"
      - "5335:53/udp"
    volumes:
      - './unbound:/opt/unbound/etc/unbound/'
    restart: unless-stopped

Luego configura tu stack de Pi-hole para usar Unbound cambiando en el docker-compose.yml:

FTLCONF_dns_upstreams: '172.17.0.1#5335'

Monitorización con Prometheus + Grafana

Exporta métricas de tu instalación de Pi-hole a Prometheus añadiendo el exporter oficial:

  pihole-exporter:
    container_name: pihole-exporter
    image: ekofr/pihole-exporter:latest
    environment:
      PIHOLE_HOSTNAME: pihole
      PIHOLE_PASSWORD: TuContraseñaSegura123!
    ports:
      - "9617:9617"
    restart: unless-stopped

Actualizar Pi-hole Docker Compose

Mantener pi-hole docker compose actualizado es crucial para seguridad y nuevas funcionalidades:

# 1. Descarga la última imagen
docker compose pull

# 2. Detén y elimina el contenedor actual
docker compose down

# 3. Recrea con la nueva versión
docker compose up -d

# 4. Verifica logs
docker logs pihole --tail 50

# 5. Comprueba versión
docker exec pihole pihole -v

Importante: Antes de actualizar de versiones antiguas (2024.x) a las nuevas (2025.x) de Pi-hole, lee las release notes en GitHub oficial de Pi-hole ya que hay cambios incompatibles en variables de entorno.

FAQ sobre Pi-hole Docker Compose

¿Cuántos recursos consume Pi-hole?

Tu instalación pi-hole docker compose es extremadamente ligera. En una red doméstica típica con 15-20 dispositivos, consume aproximadamente:

• CPU: 1-5% en promedio
• RAM: 50-150 MB
• Disco: 500 MB incluyendo logs
• Red: Tráfico mínimo (solo consultas DNS, ~1-5 KB por consulta)

Puede ejecutarse perfectamente en una Raspberry Pi Zero o en un VPS de bajo costo.

¿Puedo usar Pi-hole fuera de mi red local?

Sí, mediante VPN. La mejor solución es combinar pi-hole docker compose con Tailscale o WireGuard para acceder a tu DNS desde cualquier lugar. Esto te permite bloquear anuncios incluso en redes públicas y datos móviles.

¿Qué pasa si Pi-hole falla?

Si el contenedor pi-hole docker compose cae, los dispositivos intentarán usar el DNS secundario configurado en tu router (generalmente 8.8.8.8 o 1.1.1.1). No perderás conexión a internet, pero temporalmente no habrá bloqueo de anuncios. Por eso es crucial configurar restart: unless-stopped en el compose.

¿Es compatible con IPv6?

Sí, pi-hole docker compose soporta IPv6 completamente. Asegúrate de tener habilitado IPv6 en Docker y configura FTLCONF_dns_ipv6: 'true' en las variables de entorno. También deberás configurar tu router para distribuir la IPv6 de tu servidor Pi-hole via DHCPv6.

¿Puedo ejecutar múltiples instancias de Pi-hole?

Sí, para alta disponibilidad puedes tener dos stacks pi-hole docker compose en diferentes servidores. Configura ambas IPs como DNS primario y secundario en tu router. Esto asegura que si una falla, la otra continúa bloqueando anuncios.

Conclusión

Pi-hole Docker Compose es la herramienta indispensable para cualquiera que valore su privacidad y quiera una experiencia de navegación libre de anuncios en todos sus dispositivos. Con solo 10 minutos de configuración inicial usando pi-hole docker compose, obtienes protección de nivel empresarial para toda tu red doméstica.

Los beneficios de implementar pi-hole docker compose son inmediatos: navegación más rápida, menor consumo de datos, bloqueo de rastreadores invasivos y protección contra malware. Además, al usar Docker Compose, el mantenimiento es trivial: actualizaciones en segundos, backups automáticos y portabilidad total.

Si aún no lo has probado, este es el momento perfecto para desplegar pi-hole docker compose, tomar el control de tu red y decir adiós a los anuncios intrusivos para siempre. Tu smart TV, tu móvil y todos tus dispositivos IoT te lo agradecerán.

Para más guías sobre servicios autohospedados con Docker Compose, visita nuestra sección de artículos Docker Compose.