Cómo instalar y configurar Frigate con Docker: Guía Completa

Frigate permite crear un sistema de videovigilancia local capaz de grabar cámaras IP y utilizar modelos de inteligencia artificial para detectar personas, vehículos, animales y otros objetos. Todo el procesamiento puede realizarse dentro de tu propia red, sin enviar continuamente las imágenes a los servidores del fabricante.

Además de ofrecer mayor control sobre la privacidad, Frigate permite centralizar varias cámaras de vigilancia, conservar únicamente las grabaciones importantes y generar eventos que después pueden utilizarse en Home Assistant.

La forma recomendada de instalarlo es mediante Docker Compose. Sin embargo, Frigate no es un contenedor convencional: decodificar varios flujos de vídeo y ejecutar modelos de detección consume bastantes recursos. Para conseguir una instalación estable hay que preparar correctamente el almacenamiento, la memoria compartida, los streams de las cámaras y el acceso al hardware.

Qué hardware y sistema operativo necesitas

Frigate funciona mejor sobre Docker instalado directamente en una distribución Linux basada en Debian. Esta configuración reduce la sobrecarga y facilita el acceso a la GPU, al acelerador de inteligencia artificial y a otros dispositivos físicos.

También puede ejecutarse dentro de una máquina virtual, pero tendrás que configurar correctamente el passthrough del hardware. En Proxmox, la documentación recomienda utilizar una máquina virtual QEMU para ejecutar Docker. Instalar Frigate dentro de un contenedor LXC es posible, pero no está soportado oficialmente y puede complicar el acceso a dispositivos como /dev/dri, un Coral USB o una NPU.

Una Raspberry Pi puede servir para una instalación pequeña, especialmente si utiliza un acelerador y un almacenamiento externo. Sin embargo, el rendimiento dependerá del número de cámaras, la resolución, el códec y las funciones activadas. También debes vigilar la alimentación si conectas simultáneamente un Coral USB y un SSD, ya que puede ser necesario utilizar un concentrador USB con alimentación propia.

Antes de empezar, comprueba estos requisitos:

• Un servidor Linux con Docker y el complemento Docker Compose.
• Una o varias cámaras compatibles con RTSP.
• Una conexión de red estable, preferiblemente mediante Ethernet.
• Espacio suficiente para las grabaciones.
• Una GPU, NPU o acelerador compatible si vas a utilizar detección de objetos.
• Un broker MQTT solamente si quieres integrar Frigate con Home Assistant.

Frigate utiliza varias rutas internas que deben tenerse en cuenta al crear el contenedor:

• /config almacena el archivo de configuración, la base de datos SQLite y otros datos necesarios.
• /media/frigate contiene las grabaciones, capturas y exportaciones.
• /tmp/cache guarda temporalmente los segmentos de vídeo antes de procesarlos.
• /dev/shm conserva en memoria los fotogramas decodificados.

Es recomendable montar /tmp/cache como tmpfs. De esta manera, los segmentos temporales se escriben en la memoria RAM y se reducen las escrituras innecesarias en el SSD. No debes mapear manualmente /dev/shm; su capacidad se controla mediante el parámetro shm_size de Docker.

Cómo calcular la memoria compartida de Frigate

Docker asigna normalmente 64 MB de memoria compartida a cada contenedor. Frigate utiliza este espacio para almacenar los fotogramas decodificados, por lo que esa cantidad puede resultar insuficiente cuando se conectan varias cámaras.

Cuando la memoria compartida se agota, el contenedor puede detenerse y mostrar el mensaje “Bus error”. Un valor de 128 MB suele ser suficiente para dos cámaras cuya detección se realiza a 720p, pero las instalaciones con más cámaras o streams de mayor resolución necesitarán una cantidad superior.

El cálculo depende de la resolución del stream utilizado para la detección, no de la resolución del vídeo destinado a la grabación. Frigate ofrece esta fórmula orientativa:

(anchura × altura × 1,5 × 20 + 270480) ÷ 1048576

Al resultado de todas las cámaras hay que añadir aproximadamente 40 MB para los registros almacenados en memoria. También puedes utilizar la calculadora de SHM disponible en la documentación oficial.

En el archivo de Docker Compose, el ajuste se introduce así:

shm_size: "512mb"

Los 512 MB son un punto de partida razonable para una instalación doméstica con varias cámaras, pero no constituyen un valor obligatorio. Si el contenedor sigue mostrando un Bus error después de aumentarlo, revisa también los límites de procesos y archivos abiertos.

Aceleración de vídeo y detección mediante inteligencia artificial

Frigate realiza dos trabajos diferentes que no deben confundirse. Por un lado, FFmpeg tiene que decodificar los streams de vídeo. Por otro, un detector ejecuta el modelo de inteligencia artificial para reconocer los objetos.

La decodificación puede acelerarse mediante una GPU integrada de Intel o AMD, una tarjeta gráfica Nvidia u otro hardware compatible. Para ello se configuran los dispositivos correspondientes en Docker y los valores adecuados de hwaccel_args en Frigate.

La detección de objetos puede ejecutarse mediante varios sistemas:

• Google Coral Edge TPU: disponible en versiones USB, M.2 y Mini PCIe.
• OpenVINO: apropiado para procesadores, GPU integradas y tarjetas Arc de Intel.
• Hailo-8 y Hailo-8L: disponibles para equipos x86 y placas como Raspberry Pi 5.
• Nvidia: mediante la imagen específica de Frigate compatible con TensorRT.
• AMD ROCm: para determinadas tarjetas gráficas AMD compatibles.
• MemryX MX3: una opción soportada por la comunidad que requiere sus controladores y componentes adicionales.

El detector basado únicamente en CPU resulta útil para probar la instalación, pero no suele ser la mejor elección para utilizar varias cámaras de manera permanente. El consumo dependerá del modelo empleado, la resolución de detección, los fotogramas por segundo y la cantidad de movimiento presente en la imagen.

Si utilizas un Coral USB, normalmente tendrás que pasar el bus USB al contenedor:

devices:
  - /dev/bus/usb:/dev/bus/usb

Para una GPU Intel o AMD basada en VAAPI, suele utilizarse un dispositivo como:

devices:
  - /dev/dri/renderD128:/dev/dri/renderD128

Estas rutas pueden cambiar según el equipo. Compruébalas en el host y añade únicamente los dispositivos que realmente necesites. Ejecutar permanentemente el contenedor como privilegiado facilita algunas pruebas, pero concede más permisos de los necesarios y no es la opción más segura para una instalación definitiva.

Cómo instalar Frigate con Docker Compose paso a paso

Crea dos carpetas permanentes: una para la configuración y otra para las grabaciones. Puedes utilizar, por ejemplo:

mkdir -p ~/frigate/config
mkdir -p ~/frigate/storage
cd ~/frigate

A continuación, crea un archivo llamado compose.yaml con esta configuración básica:

services:
  frigate:
    container_name: frigate
    image: ghcr.io/blakeblackshear/frigate:stable
    restart: unless-stopped
    stop_grace_period: 30s
    shm_size: "512mb"

    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./config:/config
      - ./storage:/media/frigate
      - type: tmpfs
        target: /tmp/cache
        tmpfs:
          size: 1000000000

    ports:
      - "8971:8971"
      - "8554:8554"
      - "8555:8555/tcp"
      - "8555:8555/udp"

    environment:
      FRIGATE_RTSP_PASSWORD: "CAMBIA_ESTA_CONTRASEÑA"

Este ejemplo no incluye ningún dispositivo de aceleración porque la ruta depende del hardware utilizado. Si tienes una GPU, un Coral o una NPU, añade el bloque devices correspondiente antes de iniciar el contenedor.

La etiqueta stable sirve tanto para equipos AMD64 como para Raspberry Pi con ARM64, donde utiliza una compilación optimizada. No es necesario seleccionar manualmente otra imagen para una Raspberry Pi de 64 bits. Las instalaciones con Nvidia, ROCm o determinados procesadores Rockchip sí utilizan etiquetas específicas.

Inicia el contenedor con:

docker compose up -d

La interfaz autenticada estará disponible en:

https://IP_DEL_SERVIDOR:8971

El navegador puede mostrar una advertencia porque Frigate utiliza inicialmente un certificado autofirmado. Durante el primer arranque se genera un usuario administrador y una contraseña temporal. Puedes consultarlos con:

docker logs frigate

Inicia sesión y cambia la contraseña desde Ajustes > Usuarios. La nueva contraseña debe tener al menos 12 caracteres.

Frigate también dispone del puerto 5000 para la interfaz y la API internas sin autenticación. No es recomendable publicarlo en el host ni exponerlo a internet. Está pensado principalmente para servicios que se comunican con Frigate dentro de una red Docker de confianza.

El puerto 8554 permite acceder a los restreams RTSP de go2rtc y el 8555 se utiliza para las conexiones WebRTC. Los restreams RTSP no tienen autenticación de manera predeterminada, por lo que tampoco debes exponerlos directamente a internet.

Cómo añadir una cámara y configurar sus streams

Antes de añadir una cámara, prueba su dirección RTSP mediante VLC u otro reproductor compatible. Si el stream no funciona fuera de Frigate, tampoco funcionará dentro del contenedor.

Puedes incorporar una cámara desde el asistente disponible en Ajustes > Configuración global > Gestión de cámaras. También puedes editar directamente el archivo config.yml guardado dentro del directorio montado en /config.

La configuración más eficiente utiliza normalmente dos streams:

• Un substream de menor resolución para detectar movimiento y objetos.
• Un stream principal de mayor resolución para guardar las grabaciones.

También puedes declarar las conexiones originales dentro de go2rtc y hacer que FFmpeg utilice sus restreams locales. Esto reduce el número de conexiones directas abiertas contra la cámara.

Un ejemplo básico sería el siguiente:

mqtt:
  enabled: false

go2rtc:
  streams:
    entrada_principal:
      - rtsp://usuario:{FRIGATE_RTSP_PASSWORD}@192.168.1.50:554/stream1
    entrada_sub:
      - rtsp://usuario:{FRIGATE_RTSP_PASSWORD}@192.168.1.50:554/stream2

cameras:
  entrada:
    enabled: true

    ffmpeg:
      inputs:
        - path: rtsp://127.0.0.1:8554/entrada_sub
          input_args: preset-rtsp-restream
          roles:
            - detect

        - path: rtsp://127.0.0.1:8554/entrada_principal
          input_args: preset-rtsp-restream
          roles:
            - record

    detect:
      width: 1280
      height: 720

    record:
      enabled: true

Debes sustituir el usuario, la IP, el puerto y las rutas de los streams por los valores correspondientes a tu cámara. El nombre empleado en go2rtc también debe coincidir exactamente con el incluido en la URL local.

En las versiones actuales, Frigate intenta detectar automáticamente la resolución. Aun así, definirla explícitamente puede facilitar el diagnóstico de problemas. No resulta eficiente utilizar un vídeo 4K para la detección si la cámara ofrece un substream de menor resolución.

Después de guardar el archivo, valida la configuración desde la propia interfaz o revisa los registros del contenedor. Si existe un error de sangrado en YAML, una ruta RTSP incorrecta o un rol duplicado, Frigate puede rechazar la configuración.

Cómo utilizar máscaras, filtros y zonas correctamente

Las máscaras de movimiento no sirven para ocultar completamente una zona ni garantizan que un objeto deje de detectarse. Su función consiste en impedir que determinados cambios de imagen activen el proceso de detección.

Son útiles para elementos como:

• La fecha y la hora superpuestas por la cámara.
• El cielo o las copas de los árboles.
• Una bandera que se mueve constantemente.
• Reflejos o elementos repetitivos que generan movimiento.

Un objeto todavía puede ser detectado dentro de una máscara de movimiento si otra parte de la imagen activa el análisis. Además, cubrir demasiada superficie dificulta el seguimiento de los objetos.

Si una pared, un árbol u otro elemento fijo se identifica repetidamente como una persona, debes utilizar una máscara de filtrado para ese tipo de objeto. Si únicamente quieres recibir avisos cuando una persona entra en el jardín o se acerca a una puerta, lo adecuado es crear una zona y utilizarla como zona obligatoria para las alertas.

Frigate permite dibujar estos polígonos desde Ajustes > Configuración de la cámara > Máscaras y zonas. Antes de añadir una máscara, utiliza la vista de depuración para comprobar dónde aparecen los cuadros de movimiento y detección.

Cómo integrar Frigate con MQTT y Home Assistant

Frigate puede funcionar y grabar cámaras sin utilizar MQTT. Sin embargo, la integración con Home Assistant necesita un broker MQTT, como Mosquitto. Frigate y Home Assistant deben conectarse al mismo servidor MQTT.

La configuración básica utiliza este formato:

mqtt:
  enabled: true
  host: 192.168.1.20
  user: usuario_mqtt
  password: contraseña_mqtt

Después de comprobar que Frigate se conecta correctamente al broker, instala la integración oficial desde HACS:

1. Abre HACS en Home Assistant.
2. Busca e instala la integración Frigate.
3. Reinicia Home Assistant.
4. Entra en Ajustes > Dispositivos y servicios.
5. Pulsa Añadir integración y selecciona Frigate.
6. Introduce la dirección de la instancia.

Si Home Assistant y Frigate comparten una red Docker segura, la integración puede comunicarse mediante el puerto interno 5000. En otras configuraciones resulta preferible utilizar el puerto autenticado 8971. No abras el puerto 5000 al exterior solamente para facilitar la integración.

Una vez conectado, Home Assistant puede utilizar los sensores, cámaras y eventos generados por Frigate para crear automatizaciones. Por ejemplo, puede enviar al móvil una captura cuando una persona entra en una zona determinada, encender una luz exterior o incluir un enlace al clip grabado.

Cómo comprobar y mantener la instalación

Después de completar la configuración, revisa el estado del contenedor:

docker compose ps

Para observar los registros en tiempo real utiliza:

docker compose logs -f frigate

Comprueba especialmente que:

• Todos los streams RTSP se abren correctamente.
• No aparecen reinicios constantes de FFmpeg.
• El detector seleccionado figura como activo.
• La memoria compartida no se agota.
• Las grabaciones se guardan en la ruta esperada.
• El disco dispone de suficiente espacio libre.

Para actualizar Frigate mediante Docker Compose, ejecuta:

docker compose pull
docker compose up -d

Antes de actualizar, guarda una copia del directorio montado en /config. Allí se encuentran el archivo YAML, la base de datos y otros ajustes necesarios para reconstruir la instalación. Las grabaciones almacenadas en /media/frigate pueden respaldarse por separado si necesitas conservarlas.

Evita publicar directamente los puertos 5000, 1984 o 8554 en internet. Para acceder a Frigate desde fuera de casa resulta más seguro utilizar una VPN o un proxy inverso correctamente configurado sobre el puerto autenticado.

Instalar Frigate con Docker permite construir un sistema de videovigilancia privado y adaptable, pero su estabilidad depende de una configuración equilibrada. Separar los streams de detección y grabación, ajustar la memoria compartida, aprovechar la aceleración disponible y limitar el acceso a los puertos internos reduce considerablemente los errores y el consumo de recursos.

Una vez conectado con Home Assistant, el sistema puede utilizar las detecciones para generar notificaciones y automatizaciones mucho más precisas que las alertas de movimiento convencionales, manteniendo las grabaciones dentro de tu propia infraestructura.