Frigate Docker Compose: Sistema NVR con IA 2025

¿Buscas una solución profesional para vigilar tu hogar o negocio sin depender de servicios en la nube? Frigate Docker Compose te permite desplegar un sistema completo de grabación de video (NVR) con detección de objetos mediante inteligencia artificial, todo ejecutándose localmente en tu servidor. En esta guía aprenderás a instalar y configurar este potente sistema de videovigilancia que procesa tus cámaras IP en tiempo real con análisis de objetos mediante redes neuronales.

Qué es Frigate Docker Compose y por qué usarlo

Frigate es un NVR (Network Video Recorder) de código abierto diseñado específicamente para integrarse con Home Assistant. A diferencia de soluciones comerciales que envían tus imágenes a la nube, esta plataforma procesa todo localmente utilizando OpenCV y TensorFlow para realizar detección de objetos en tiempo real.

Este sistema destaca por su arquitectura optimizada que utiliza multiprocesamiento para maximizar los FPS (frames por segundo) de análisis. La detección de objetos se ejecuta en procesos separados, lo que permite analizar múltiples cámaras simultáneamente sin sobrecargar tu hardware. Con más de 19,000 estrellas en GitHub y una comunidad activa de desarrolladores, se ha consolidado como el estándar de facto para NVR open source.

Las principales ventajas incluyen grabación continua 24/7, retención inteligente basada en objetos detectados, visualización en tiempo real con baja latencia mediante WebRTC, y capacidad de identificar personas, vehículos, mascotas y otros objetos de forma automática. Todo esto sin cuotas mensuales ni limitaciones artificiales de funcionalidad.

Requisitos previos para instalar Frigate Docker Compose

Antes de comenzar la instalación, asegúrate de cumplir con estos requisitos técnicos fundamentales:

• Docker y Docker Compose instalados: Necesitarás Docker Engine 20.10 o superior y Docker Compose 2.0+. Verifica con docker --version
• Hardware adecuado: Mínimo 4GB RAM, aunque se recomiendan 8GB para múltiples cámaras. Procesador de al menos 4 núcleos para detección fluida
• Almacenamiento suficiente: Depende de cuántas cámaras y días de retención quieras. Calcula aproximadamente 5-10GB por cámara por día de grabación continua a 1080p
• Cámaras IP compatibles: Cualquier cámara que soporte streaming RTSP o RTMP funcionará correctamente. Marcas populares como Hikvision, Dahua, Reolink, Amcrest y Wyze son totalmente compatibles
• Aceleración por hardware (opcional pero recomendada): GPU Intel QuickSync, Google Coral TPU, o NVIDIA GPU para mejorar significativamente el rendimiento
• Red estable: Conexión Ethernet para las cámaras (WiFi funciona pero no es ideal para streaming continuo)

Para verificar que tienes Docker instalado correctamente, ejecuta estos comandos en tu terminal:

docker --version
docker compose version

Si no tienes Docker instalado, consulta la documentación oficial para tu sistema operativo. En sistemas Linux basados en Debian/Ubuntu es tan simple como ejecutar el script de instalación oficial.

Configuración del archivo docker-compose.yml para Frigate

El primer paso es crear un directorio para tu instalación y configurar el archivo docker-compose.yml. Este archivo define todos los parámetros necesarios para ejecutar el contenedor correctamente con todos los permisos y recursos requeridos.

Crea la estructura de directorios necesaria:

mkdir -p ~/frigate/{config,storage}
cd ~/frigate

Ahora crea el archivo docker-compose.yml con la siguiente configuración optimizada para Frigate Docker Compose:

services:
  frigate:
    container_name: frigate
    privileged: true
    restart: unless-stopped
    stop_grace_period: 30s
    image: ghcr.io/blakeblackshear/frigate:stable
    shm_size: "512mb"
    devices:
      - /dev/bus/usb:/dev/bus/usb  # Para USB Coral
      - /dev/dri/renderD128:/dev/dri/renderD128  # Para aceleración Intel
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./config:/config
      - ./storage:/media/frigate
      - type: tmpfs
        target: /tmp/cache
        tmpfs:
          size: 1000000000
    ports:
      - "8971:8971"  # Interfaz web
      - "8554:8554"  # RTSP restreaming
      - "8555:8555/tcp"  # WebRTC
      - "8555:8555/udp"  # WebRTC
    environment:
      FRIGATE_RTSP_PASSWORD: "cambiar_password_seguro"

Aspectos importantes de esta configuración:

• privileged: true: Necesario para acceder al hardware de detección como Coral TPU o GPU
• shm_size: Memoria compartida calculada según tus cámaras (fórmula: ancho × alto × 1.5 × 20 + 270480 / 1048576 MB por cámara). Para 4 cámaras 1080p, 512MB es suficiente
• tmpfs en /tmp/cache: Mejora drásticamente el rendimiento usando memoria RAM para archivos temporales de detección
• Puerto 8971: Interfaz web principal para visualización y configuración en tiempo real
• Puertos 8554-8555: Permiten re-streaming RTSP y conexiones WebRTC de baja latencia

Si no vas a usar aceleración por hardware, puedes comentar o eliminar la sección devices. El sistema funcionará perfectamente con detección por CPU para 1-2 cámaras.

Archivo de configuración config.yml básico

Necesitarás crear un archivo de configuración que defina tus cámaras y ajustes de detección. Este es el cerebro de toda la instalación donde especificas qué detectar, dónde y cómo almacenar las grabaciones. Crea el archivo config/config.yml con esta configuración base:

mqtt:
  enabled: false  # Activa esto si usas Home Assistant

cameras:
  camara_entrada:
    enabled: true
    ffmpeg:
      inputs:
        - path: rtsp://usuario:[email protected]:554/stream1
          roles:
            - detect
            - record
    detect:
      width: 1920
      height: 1080
      fps: 5
    record:
      enabled: true
      retain:
        days: 7
        mode: motion
    snapshots:
      enabled: true
      retain:
        default: 14
    objects:
      track:
        - person
        - car
        - dog

  camara_jardin:
    enabled: true
    ffmpeg:
      inputs:
        - path: rtsp://usuario:[email protected]:554/stream1
          roles:
            - detect
            - record
    detect:
      width: 1920
      height: 1080
      fps: 5
    objects:
      track:
        - person
        - dog
        - cat
      filters:
        person:
          min_score: 0.65
          threshold: 0.75
    zones:
      zona_piscina:
        coordinates: 400,400,600,400,600,600,400,600
        objects:
          - person

detectors:
  cpu:
    type: cpu
    num_threads: 3

Personaliza las URLs RTSP de tus cámaras según el fabricante. Por ejemplo, Hikvision suele usar el path /Streaming/Channels/101, mientras que Reolink usa /h264Preview_01_main. Consulta la documentación de tu cámara o busca en las discusiones de GitHub modelos específicos.

Los objetos rastreables incluyen: person, bicycle, car, motorcycle, airplane, bus, train, truck, boat, bird, cat, dog, horse, sheep, cow, elephant, bear, zebra, giraffe, y muchos más. La lista completa está disponible en la documentación del modelo COCO utilizado por TensorFlow.

Iniciando Frigate Docker Compose por primera vez

Con los archivos de configuración listos, es momento de iniciar el servicio y comprobar que todo funciona correctamente:

docker compose up -d

Verifica que el contenedor esté ejecutándose correctamente sin errores:

docker compose logs -f frigate

En los logs deberías ver mensajes indicando que las cámaras se están conectando y que el detector está inicializando. Busca líneas que confirmen:

• Conexión exitosa a cada cámara RTSP
• Inicialización del detector (CPU, Coral, etc.)
• Inicio de los procesos de captura y detección
• WebRTC y RTSP servers escuchando en sus puertos

Si hay errores de conexión RTSP, verifica las URLs y credenciales de tus cámaras. Los errores más comunes incluyen contraseñas incorrectas, paths RTSP equivocados, o firewalls bloqueando el puerto 554.

Accede a la interfaz web navegando a http://tu-ip-servidor:8971. Deberías ver el dashboard principal con visualización en vivo de tus cámaras y los eventos de detección en tiempo real. La interfaz es intuitiva con pestañas para cámaras, eventos, grabaciones y configuración.

Optimización del rendimiento con aceleración por hardware

Para procesar múltiples cámaras de alta resolución, la detección por CPU puede ser insuficiente o consumir demasiados recursos. El sistema soporta varios aceleradores de hardware que multiplican el rendimiento y reducen drásticamente el uso de CPU.

Google Coral TPU

El Google Coral es el acelerador recomendado por la comunidad debido a su excelente relación rendimiento/precio. Un Coral USB puede procesar hasta 100 FPS de detección. Modifica tu configuración:

detectors:
  coral:
    type: edgetpu
    device: usb

Para verificar que el Coral está siendo reconocido, ejecuta lsusb y busca «Global Unichip Corp.» Asegúrate de tener instalados los drivers Edge TPU en tu sistema host.

Aceleración Intel QuickSync

Si tienes una CPU Intel con GPU integrada (generación 6 o superior), puedes usarla para decodificar video y liberar recursos de CPU:

ffmpeg:
  hwaccel_args: preset-vaapi

cameras:
  tu_camara:
    ffmpeg:
      hwaccel_args: preset-vaapi

Asegúrate de que el dispositivo /dev/dri/renderD128 está mapeado en tu docker-compose.yml. Verifica los permisos con ls -la /dev/dri/ y añade tu usuario al grupo render si es necesario.

NVIDIA GPU

Para GPUs NVIDIA necesitarás el NVIDIA Container Toolkit instalado. La configuración es más compleja pero ofrece excelente rendimiento:

ffmpeg:
  hwaccel_args: preset-nvidia-h264

cameras:
  tu_camara:
    ffmpeg:
      hwaccel_args: preset-nvidia-h264

También debes añadir el runtime de NVIDIA en tu docker-compose.yml con la directiva runtime: nvidia y mapear los dispositivos GPU.

Configuración avanzada: zonas y máscaras de detección

Una característica extremadamente poderosa es la capacidad de definir zonas específicas donde quieres detectar objetos, ignorando otras áreas que generan falsas alarmas como árboles moviéndose, sombras o reflejos de luz.

Desde la interfaz web, haz clic en una cámara y selecciona el editor de máscaras en el menú superior. Puedes dibujar polígonos arrastrando el ratón para definir:

• Zonas de detección: Áreas específicas donde quieres recibir alertas (entrada principal, garaje, ventanas)
• Máscaras de movimiento: Áreas que ignorar completamente para evitar falsos positivos (árboles que se mueven con el viento, reflejos en ventanas, relojes con segundero)
• Zonas de objetos específicos: Detectar solo personas en la entrada, solo vehículos en el garaje, solo mascotas en el jardín

Las coordenadas se exportan automáticamente y puedes copiarlas al archivo config.yml para persistirlas entre reinicios. El formato es una lista de coordenadas X,Y que forman un polígono cerrado.

Por ejemplo, para crear una zona que solo detecte personas en la puerta principal y evite alertas de coches pasando por la calle:

zones:
  entrada_principal:
    coordinates: 350,150,850,150,850,700,350,700
    objects:
      - person
    filters:
      person:
        min_score: 0.70

Integración con Home Assistant

La integración nativa con Home Assistant convierte a este NVR en una solución completa de domótica. Primero, habilita MQTT en ambos sistemas ya que es el protocolo de comunicación utilizado.

En tu config.yml de la aplicación, añade la configuración MQTT:

mqtt:
  enabled: true
  host: 192.168.1.50
  user: mqtt_user
  password: mqtt_password
  topic_prefix: frigate
  client_id: frigate

En Home Assistant, instala la integración oficial de la herramienta desde HACS (Home Assistant Community Store). Si no tienes HACS, primero instálalo siguiendo su documentación oficial. Una vez instalada la integración, ve a Configuración → Integraciones → Añadir integración y busca el nombre del servicio.

Una vez conectada, tendrás acceso automático a:

• Entidades de cámara para cada stream configurado
• Sensores binarios de detección de objetos (person_detected, car_detected, etc.)
• Servicios para activar/desactivar grabación y detección dinámicamente
• Notificaciones con snapshots cuando se detectan eventos específicos
• Estadísticas de rendimiento y uso de recursos

Puedes crear automatizaciones potentes como encender luces cuando se detecta una persona de noche, enviar notificaciones push con la imagen del evento a tu móvil, activar sirenas si se detecta movimiento cuando no hay nadie en casa, o incluso crear escenas que desactiven la detección cuando llegues a casa.

Ejemplo de automatización para notificaciones:

automation:
  - alias: "Alerta persona en entrada"
    trigger:
      - platform: mqtt
        topic: frigate/events
        payload: "person"
    condition:
      - condition: state
        entity_id: alarm_control_panel.casa
        state: "armed_away"
    action:
      - service: notify.mobile_app
        data:
          message: "Persona detectada en entrada principal"
          data:
            image: "/api/frigate/notifications/{{trigger.payload_json.id}}/snapshot.jpg"

Gestión del almacenamiento y retención

La grabación continua 24/7 consume mucho espacio de almacenamiento. El sistema implementa una retención inteligente que prioriza grabaciones con eventos detectados, descartando segmentos sin actividad relevante.

Configuración de retención recomendada para balance entre seguridad y almacenamiento:

record:
  enabled: true
  retain:
    days: 7  # Grabación continua 7 días
    mode: motion  # Solo segmentos con movimiento
  events:
    retain:
      default: 30  # Clips con objetos detectados 30 días
      mode: active_objects
    objects:
      person: 60  # Eventos con personas 60 días
      car: 14     # Eventos con vehículos 14 días

El modo active_objects mantiene las grabaciones donde hay objetos rastreados activamente, descartando movimiento irrelevante como sombras, cambios de luz, insectos volando cerca de la cámara o vegetación moviéndose.

Monitorea el uso de disco periódicamente con:

du -sh ~/frigate/storage/
df -h ~/frigate/storage/

Considera implementar un sistema de limpieza automática con cron jobs si te quedas sin espacio frecuentemente, o aumenta el almacenamiento con discos duros adicionales específicos para videovigilancia (como WD Purple).

Resolución de problemas comunes

Durante la configuración y uso diario pueden surgir varios problemas típicos. Aquí las soluciones a los más frecuentes:

Error de conexión RTSP

Si las cámaras no conectan, verifica primero la URL RTSP con VLC Media Player. Abre VLC → Medio → Abrir ubicación de red y pega tu URL RTSP. El formato típico varía por fabricante:

• Hikvision: rtsp://admin:[email protected]:554/Streaming/Channels/101
• Reolink: rtsp://admin:[email protected]:554/h264Preview_01_main
• Dahua: rtsp://admin:[email protected]:554/cam/realmonitor?channel=1&subtype=0
• Amcrest: rtsp://admin:[email protected]:554/cam/realmonitor?channel=1&subtype=1

Consulta la documentación de tu cámara o busca en GitHub Discussions para el path correcto de tu modelo específico.

Alto uso de CPU

Si el CPU está constantemente al 100%, implementa estas soluciones escalonadas:

1. Reduce el FPS de detección de 5 a 3 FPS (más que suficiente para detección efectiva)
2. Reduce la resolución del stream de detección a 720p en lugar de 1080p
3. Implementa aceleración por hardware (Coral TPU o QuickSync)
4. Ajusta el número de threads del detector CPU

Falsas detecciones

Las falsas alarmas son el problema más reportado. Ajusta los umbrales de confianza y usa máscaras para áreas problemáticas:

objects:
  filters:
    person:
      min_score: 0.65  # Aumenta si hay muchos falsos positivos
      threshold: 0.75  # Umbral para considerar tracking
      min_area: 5000   # Área mínima en píxeles
      max_area: 100000 # Área máxima (evita detecciones erróneas gigantes)

Contenedor reiniciándose constantemente

Si el contenedor se reinicia en loop, revisa los logs detalladamente:

docker compose logs frigate | tail -100

Causas comunes incluyen errores de sintaxis en config.yml, memoria compartida insuficiente, o permisos incorrectos en los directorios de volúmenes.

Seguridad y acceso remoto seguro

Para acceder remotamente de forma segura a tu sistema de videovigilancia, evita exponer el puerto 8971 directamente a Internet. Esta es una práctica peligrosa que te expone a ataques de fuerza bruta y vulnerabilidades zero-day.

Las mejores opciones para acceso remoto seguro son:

Opción 1: Proxy inverso con autenticación

Si utilizas Nginx Proxy Manager o Caddy, configura HTTPS con certificados Let’s Encrypt y autenticación básica o OAuth:

frigate.tudominio.com {
    reverse_proxy frigate:8971
    basicauth {
        usuario $2a$14$hash_bcrypt_aqui
    }
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
}

Para generar el hash bcrypt del password, usa: docker run --rm caddy:latest caddy hash-password --plaintext 'tupassword'

Opción 2: VPN (Recomendado)

La opción más segura es usar una VPN como WireGuard o Tailscale. Estas soluciones crean un túnel cifrado sin exponer puertos públicamente. Tailscale es especialmente fácil de configurar y gratuita para uso personal.

Con Tailscale instalado en tu servidor y dispositivos móviles, accedes a http://ip-tailscale:8971 desde cualquier lugar de forma segura.

Opción 3: Cloudflare Tunnel

Cloudflare Tunnel permite exponer servicios sin abrir puertos en tu router. Es gratuito y ofrece protección DDoS incluida. Requiere configurar cloudflared como contenedor adicional.

Actualizaciones y mantenimiento del sistema

Mantener actualizado el sistema es crucial para seguridad, corrección de bugs y acceso a nuevas funcionalidades. El proyecto tiene un ciclo de lanzamiento activo con mejoras constantes cada 2-4 semanas.

Para actualizar a la última versión stable de forma segura:

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

Siempre revisa el changelog en GitHub antes de actualizar para conocer cambios que puedan requerir ajustes en tu configuración. Algunas actualizaciones mayores requieren migración de base de datos o cambios en el formato del config.yml.

Realiza backups periódicos de tu directorio de configuración y base de datos:

tar -czf frigate-config-backup-$(date +%Y%m%d).tar.gz ~/frigate/config/

Automatiza los backups con un cron job semanal:

0 3 * * 0 tar -czf /backups/frigate-$(date +\%Y\%m\%d).tar.gz ~/frigate/config/

Comparativa con otras soluciones NVR

En el ecosistema de NVR open source existen varias alternativas con diferentes enfoques y capacidades. Entender las diferencias te ayudará a validar si esta es la mejor opción para tu caso de uso.

Comparado con Zoneminder, esta solución es significativamente más moderna y eficiente en recursos. Mientras Zoneminder requiere configuración compleja con Apache/MySQL y consume muchos recursos del sistema, la herramienta que analizamos está optimizada desde el diseño con arquitectura de contenedores y procesamiento eficiente.

Frente a MotionEye, la principal ventaja es la detección de objetos con IA. MotionEye solo hace detección básica de movimiento pixel por pixel, generando muchas falsas alarmas por sombras, insectos o cambios de iluminación. La capacidad de identificar específicamente personas, vehículos o mascotas reduce drásticamente los falsos positivos.

Comparado con soluciones comerciales como Blue Iris o sistemas propietarios de cámaras (Arlo, Nest, Ring), obtienes control total de tus datos sin que tus imágenes sean enviadas a servidores externos, sin suscripciones mensuales que pueden costar $10-30/mes por cámara, y la posibilidad de personalizar cada aspecto del funcionamiento según tus necesidades.

Versus Shinobi, otra solución moderna, la ventaja está en la integración nativa con Home Assistant y la comunidad más activa. Shinobi ofrece una interfaz más tradicional de NVR, mientras que esta herramienta está diseñada específicamente para smart homes.

Casos de uso prácticos y escenarios reales

Los usuarios implementan esta tecnología en diversos escenarios con resultados impresionantes:

Seguridad residencial avanzada

Monitorización de múltiples puntos de entrada con alertas inteligentes. Un usuario reporta haber configurado 6 cámaras cubriendo todas las entradas de su casa, con zonas específicas que solo alertan cuando detectan personas en horario nocturno, ignorando animales y vehículos. Las grabaciones de eventos con personas se mantienen 90 días, mientras que la grabación continua solo 3 días.

Vigilancia de mascotas

Seguimiento automático de perros y gatos con alertas si salen de zonas permitidas. Un usuario configuró zonas de seguridad en su jardín y recibe notificaciones si su perro cruza hacia áreas peligrosas cerca de la piscina o portón de salida.

Pequeños negocios y comercios

Control de acceso, monitorización de áreas de almacén y cajas registradoras. Un propietario de tienda usa el sistema con 8 cámaras, reteniendo eventos con personas durante 6 meses para investigaciones de inventario. La integración con Home Assistant le permite desactivar automáticamente las alertas durante horario comercial.

Granjas y propiedades rurales

Detección de animales salvajes, vigilancia de ganado y protección de cultivos. Un granjero monitoriza 4 hectáreas con 12 cámaras, detectando coyotes y jabalíes que se acercan por la noche, activando automáticamente luces y sirenas disuasorias.

Automatización del hogar inteligente

Activación de luces basada en presencia, análisis de patrones de movimiento para rutinas, y detección de paquetes dejados en la puerta. La flexibilidad de las zonas, filtros y la integración con Home Assistant permite adaptar el comportamiento a necesidades muy específicas de cada hogar.

Preguntas frecuentes (FAQ)

¿Cuántas cámaras puedo conectar a Frigate Docker Compose?

No hay un límite fijo definido por software. Depende completamente de tu hardware, resolución de cámaras y tipo de detector utilizado. Con detección por CPU en un servidor modesto, generalmente 2-4 cámaras a 1080p funcionan bien. Con Google Coral TPU, puedes manejar fácilmente 8-15 cámaras sin problemas. Usuarios avanzados con hardware dedicado reportan instalaciones con más de 30 cámaras usando múltiples Coral y servidores potentes con CPUs Xeon o Ryzen de 16+ núcleos.

¿Funciona con cámaras WiFi?

Sí, funciona perfectamente siempre que la cámara soporte streaming RTSP o RTMP. Sin embargo, se recomienda encarecidamente usar conexión Ethernet cableada para cámaras de vigilancia debido a la estabilidad y ancho de banda consistente que requiere la grabación continua 24/7. WiFi puede sufrir interferencias, desconexiones temporales y ancho de banda variable que afectan la calidad.

¿Necesito Home Assistant obligatoriamente?

No. La aplicación funciona completamente de forma autónoma con su propia interfaz web completa y profesional. La integración con Home Assistant es opcional y añade capacidades de automatización avanzadas, pero no es un requisito para usar el sistema. Puedes perfectamente usar solo el NVR sin ninguna plataforma de domótica.

¿Puedo usar reconocimiento facial?

El sistema base no incluye reconocimiento facial por defecto. Detecta «personas» como categoría general sin identificar individuos. Existen integraciones comunitarias experimentales con CompreFace y Double-Take para añadir reconocimiento facial, aunque requieren configuración adicional avanzada y mayor potencia de procesamiento.

¿Qué pasa si se va la luz o se reinicia el servidor?

Con la configuración restart: unless-stopped en el archivo Docker Compose, el servicio se reinicia automáticamente cuando vuelve la electricidad o el servidor se reinicia. El sistema recupera la configuración y continúa grabando normalmente. Se recomienda usar un SAI (UPS) para evitar corrupción de datos en la base de datos SQLite durante cortes de energía abruptos.

Conclusión

Implementar un sistema de videovigilancia profesional con detección de objetos por inteligencia artificial ya no requiere costosas suscripciones ni dependencia de servicios cloud que procesan tus imágenes en servidores remotos. Con Frigate Docker Compose obtienes un NVR completo, eficiente y totalmente bajo tu control que rivaliza con soluciones empresariales que cuestan miles de dólares.

La combinación de grabación continua 24/7, análisis inteligente con IA capaz de distinguir personas de vehículos y mascotas, integración nativa con Home Assistant para automatizaciones avanzadas, y la flexibilidad de Docker lo convierten en la solución ideal para homelabs y proyectos de seguridad self-hosted. Ya sea que necesites monitorizar tu hogar, pequeño negocio, granja o simplemente aprender sobre sistemas de visión por computadora, esta herramienta ofrece capacidades de nivel empresarial accesibles para todos sin coste de licencias.

La comunidad extremadamente activa en GitHub con más de 19,000 estrellas, la documentación oficial exhaustiva, y los foros de discusión aseguran soporte constante, resolución rápida de problemas y evolución continua del proyecto con nuevas características cada mes. Comienza con una o dos cámaras para familiarizarte con la configuración, experimenta con zonas y detección de objetos, y expande tu sistema según tus necesidades y presupuesto crezcan.

El futuro de la videovigilancia residencial es local, privado y open source. No esperes más para tomar control total de la seguridad de tu hogar o negocio.