Home Assistant Docker Compose: Automatiza Tu Casa Inteligente 2025

¿Buscas controlar todos tus dispositivos inteligentes desde una única plataforma? Home Assistant Docker Compose es la solución definitiva para automatizar tu hogar sin depender de servicios en la nube. En esta guía completa aprenderás a instalar y configurar Home Assistant usando Docker Compose, creando un sistema de domótica profesional en minutos.

¿Qué es Home Assistant Docker Compose?

Home Assistant Docker Compose es una plataforma de automatización del hogar de código abierto que prioriza el control local y la privacidad. Con más de 82,000 estrellas en GitHub y una comunidad de 4,400+ contribuidores, Home Assistant se ha convertido en la solución líder para domótica autoalojada en 2025.

A diferencia de sistemas propietarios como Google Home o Alexa, Home Assistant funciona completamente en tu servidor local, garantizando que tus datos permanezcan privados. Soporta más de 1,000 integraciones con dispositivos y servicios, desde bombillas Philips Hue hasta termostatos Nest, pasando por sensores Zigbee y cámaras de seguridad.

La implementación con Docker Compose simplifica enormemente el despliegue y mantenimiento del sistema, permitiéndote tener Home Assistant funcionando en cuestión de minutos sin complicadas configuraciones manuales.

Ventajas de usar Home Assistant Docker Compose

Implementar Home Assistant Docker Compose ofrece múltiples beneficios sobre otros métodos de instalación:

Portabilidad total: Migra tu instalación entre servidores simplemente copiando la carpeta de configuración
Aislamiento del sistema: Home Assistant funciona en un contenedor sin afectar otros servicios de tu servidor
Actualizaciones sencillas: Actualiza a la última versión cambiando una sola línea en tu archivo compose.yaml
Gestión declarativa: Define toda tu infraestructura como código, facilitando el control de versiones y respaldos
Integración con otros servicios: Combina fácilmente Home Assistant con bases de datos, brokers MQTT y otros contenedores
Menor consumo de recursos: Docker consume significativamente menos recursos que instalaciones con máquinas virtuales

Requisitos previos para Home Assistant Docker Compose

Antes de instalar Home Assistant Docker Compose, asegúrate de cumplir con estos requisitos:

Hardware recomendado

Procesador: CPU de 64 bits (x86_64 o ARM64)
RAM: Mínimo 1 GB, recomendado 2 GB o más
Almacenamiento: 32 GB mínimo, SSD recomendado para mejor rendimiento
Red: Conexión Ethernet estable (WiFi puede causar problemas de descubrimiento)

Home Assistant Docker Compose funciona perfectamente en Raspberry Pi 4, servidores NAS Synology, mini PCs o cualquier servidor Linux. Para proyectos más ambiciosos con múltiples integraciones, considera un servidor con 4 GB de RAM.

Software necesario

Docker Engine versión 19.03.9 o superior (NO Docker Desktop)
Docker Compose versión 2.0 o superior
Sistema operativo: Ubuntu Server 22.04/24.04, Debian 11/12, o Raspbian OS
libseccomp versión 2.4.2 o más reciente

Nota importante: Home Assistant requiere Docker Engine, no Docker Desktop. La documentación oficial especifica que Docker Desktop no funcionará correctamente debido a limitaciones en el acceso a red y dispositivos.

Instalación de Home Assistant Docker Compose paso a paso

Sigue estos pasos para instalar Home Assistant Docker Compose en tu servidor:

Paso 1: Crear la estructura de directorios

Primero, crea un directorio dedicado para almacenar la configuración de Home Assistant:

mkdir -p ~/homeassistant/config
cd ~/homeassistant

Paso 2: Crear el archivo docker-compose.yml

Crea un archivo docker-compose.yml con la siguiente configuración optimizada para Home Assistant Docker Compose:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      - TZ=Europe/Madrid
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8123"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 90s

Paso 3: Configurar variables de entorno

Personaliza las siguientes variables según tu ubicación:

TZ: Zona horaria (ejemplos: Europe/Madrid, America/Mexico_City, America/Argentina/Buenos_Aires)
./config: Ruta donde se almacenarán los archivos de configuración

El modo network_mode: host permite que Home Assistant acceda directamente a todas las interfaces de red, facilitando el descubrimiento automático de dispositivos mediante protocolos como mDNS, SSDP y UPnP.

Paso 4: Iniciar Home Assistant Docker Compose

Inicia el contenedor ejecutando:

docker compose up -d

Docker descargará la imagen de Home Assistant (aproximadamente 1.2 GB) y creará el contenedor. El proceso inicial puede tardar 2-3 minutos dependiendo de tu conexión.

Paso 5: Acceder a la interfaz web

Una vez iniciado, accede a Home Assistant Docker Compose desde tu navegador:

http://<IP-DE-TU-SERVIDOR>:8123

En el primer acceso, Home Assistant te solicitará crear una cuenta de administrador y configurar tu ubicación. Este proceso de onboarding te guiará para detectar automáticamente dispositivos compatibles en tu red.

Configuración avanzada de Home Assistant Docker Compose

Para aprovechar al máximo Home Assistant Docker Compose, considera estas configuraciones avanzadas:

Integración con Mosquitto MQTT

MQTT es esencial para dispositivos IoT como sensores Zigbee y ESP32. Añade Mosquitto a tu docker-compose.yml:

services:
  homeassistant:
    # ... configuración anterior ...

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:latest
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    ports:
      - "1883:1883"
      - "9001:9001"
    restart: unless-stopped

Base de datos MariaDB para historial largo

Por defecto, Home Assistant usa SQLite que puede volverse lento con el tiempo. MariaDB mejora significativamente el rendimiento:

  mariadb:
    container_name: mariadb
    image: mariadb:latest
    environment:
      MYSQL_ROOT_PASSWORD: tu_password_segura
      MYSQL_DATABASE: homeassistant
      MYSQL_USER: hauser
      MYSQL_PASSWORD: tu_password_ha
    volumes:
      - ./mariadb:/var/lib/mysql
    restart: unless-stopped
    ports:
      - "3306:3306"

Luego configura Home Assistant editando config/configuration.yaml:

recorder:
  db_url: mysql://hauser:tu_password_ha@mariadb/homeassistant?charset=utf8mb4
  purge_keep_days: 30
  auto_purge: true

Acceso a dispositivos USB

Si usas dongles Zigbee, Z-Wave o Bluetooth, necesitas mapear el dispositivo USB en Home Assistant Docker Compose:

services:
  homeassistant:
    # ... configuración anterior ...
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0  # Zigbee/Z-Wave
      - /dev/ttyACM0:/dev/ttyACM0  # Alternativa

Para identificar tu dispositivo, ejecuta ls -la /dev/tty* antes y después de conectar el dongle.

Integraciones esenciales para Home Assistant Docker Compose

Una vez instalado Home Assistant Docker Compose, estas son las integraciones más populares para 2025:

Zigbee2MQTT: Control de dispositivos Zigbee sin hubs propietarios
ESPHome: Crea sensores personalizados con microcontroladores ESP32/ESP8266
Node-RED: Automatizaciones avanzadas con programación visual
AdGuard Home: Bloqueo de anuncios y DNS seguro para toda tu red
Frigate: Detección de objetos con IA en cámaras de seguridad
InfluxDB + Grafana: Visualización avanzada de datos históricos

Todas estas integraciones se pueden desplegar como servicios adicionales en tu archivo docker-compose.yml, creando un ecosistema completo de hogar inteligente.

Mantenimiento y actualizaciones de Home Assistant Docker Compose

Mantener actualizado Home Assistant Docker Compose es fundamental para seguridad y nuevas funcionalidades:

Actualizar a la última versión

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

Home Assistant lanza actualizaciones mensuales el primer miércoles de cada mes, con parches de seguridad cuando son necesarios. La etiqueta :stable siempre apunta a la última versión estable recomendada.

Realizar backups automáticos

Protege tu configuración creando backups regulares:

#!/bin/bash
# Script de backup automático
BACKUP_DIR="/ruta/backups/homeassistant"
DATE=$(date +%Y%m%d_%H%M%S)

tar -czf "$BACKUP_DIR/ha_backup_$DATE.tar.gz" -C ~/homeassistant config
find "$BACKUP_DIR" -name "ha_backup_*.tar.gz" -mtime +30 -delete

Programa este script con cron para ejecutarse diariamente a las 3 AM:

0 3 * * * /ruta/backup_homeassistant.sh

Monitorizar logs

Para diagnosticar problemas en Home Assistant Docker Compose:

# Ver logs en tiempo real
docker compose logs -f homeassistant

# Ver últimas 100 líneas
docker compose logs --tail=100 homeassistant

Solución de problemas comunes en Home Assistant Docker Compose

El contenedor no inicia correctamente

Si Home Assistant Docker Compose no arranca, verifica:

Permisos del directorio config: debe ser accesible por UID 1000
Puerto 8123 no esté ocupado: sudo netstat -tlnp | grep 8123
Versión de libseccomp: dpkg -l | grep libseccomp (debe ser ≥ 2.4.2)

Dispositivos no se descubren automáticamente

El descubrimiento automático requiere network_mode: host. Si usas redes bridge personalizadas, necesitarás configurar manualmente las integraciones.

Error de permisos con dispositivos USB

Añade tu usuario al grupo dialout:

sudo usermod -aG dialout $USER
sudo chmod 666 /dev/ttyUSB0

Comparativa: Home Assistant Docker Compose vs otras instalaciones

Característica	Docker Compose	Home Assistant OS	Instalación Core
Facilidad de instalación	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐
Soporte para Add-ons	❌	✅	❌
Flexibilidad del sistema	✅	❌	✅
Consumo de recursos	Bajo	Medio	Muy bajo
Actualizaciones	Manual/Automatizable	Automáticas	Manual
Integración con otros servicios	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐

Home Assistant Docker Compose ofrece el mejor equilibrio entre facilidad de uso, flexibilidad y control del sistema. Es ideal si ya tienes un servidor Linux y quieres combinar Home Assistant con otros servicios como Plex, Nextcloud o Dockge.

Recursos y comunidad para Home Assistant Docker Compose

La comunidad de Home Assistant Docker Compose es extremadamente activa. Estos recursos te serán útiles:

Documentación oficial: home-assistant.io – Guías completas y referencia de API
Foro comunitario: community.home-assistant.io – Más de 100,000 usuarios activos
GitHub: github.com/home-assistant/core – Reporta bugs y solicita funcionalidades
Reddit: r/homeassistant – 500,000+ miembros compartiendo proyectos
Discord: Servidor oficial con canales especializados por idioma

Además, explora otros artículos relacionados en nuestra categoría Docker Compose para aprender sobre Ollama y otros servicios autoalojados.

Preguntas frecuentes sobre Home Assistant Docker Compose

¿Puedo usar Docker Desktop en lugar de Docker Engine para Home Assistant?

No, la documentación oficial de Home Assistant especifica que Docker Desktop no funcionará correctamente. Docker Desktop tiene limitaciones en el acceso a la red del host y dispositivos que son esenciales para el funcionamiento de Home Assistant. Debes usar Docker Engine en Linux.

¿Home Assistant Docker Compose soporta add-ons oficiales?

No, los add-ons son exclusivos de Home Assistant OS. Sin embargo, con Docker Compose puedes lograr la misma funcionalidad desplegando los servicios equivalentes como contenedores independientes (Mosquitto, AdGuard Home, etc.), lo que ofrece más flexibilidad.

¿Qué hardware es mejor para ejecutar Home Assistant Docker Compose?

Una Raspberry Pi 4 con 4 GB de RAM es suficiente para instalaciones pequeñas-medianas (hasta 50 dispositivos). Para configuraciones más grandes o si planeas usar cámaras con detección de IA, considera un mini PC con procesador x86 e Intel QuickSync para aceleración de video.

¿Cómo migro de Home Assistant OS a Home Assistant Docker Compose?

Crea un snapshot en Home Assistant OS, descarga el archivo, extrae la carpeta homeassistant del archivo tar, y cópiala al directorio config de tu instalación Docker Compose. Luego reinicia el contenedor y tu configuración completa estará disponible.

¿Es seguro exponer Home Assistant a Internet?

No expongas directamente el puerto 8123 a Internet. Usa Home Assistant Cloud (Nabu Casa) para acceso remoto seguro, o implementa un reverse proxy con certificados SSL (Nginx Proxy Manager, Traefik) junto con autenticación multifactor. Nunca expongas Home Assistant sin protección adicional.

Conclusión: Tu sistema de domótica profesional con Home Assistant Docker Compose

Home Assistant Docker Compose representa la solución perfecta para construir un ecosistema de hogar inteligente potente, privado y totalmente bajo tu control. Con más de 1,000 integraciones disponibles, una comunidad activa de millones de usuarios y actualizaciones mensuales, Home Assistant se consolida como la plataforma líder de domótica de código abierto en 2025.

La implementación con Docker Compose simplifica drásticamente el despliegue y mantenimiento, permitiéndote tener un sistema profesional funcionando en minutos. Ya sea que estés empezando con unas pocas bombillas inteligentes o construyendo un sistema completo con cientos de dispositivos, sensores personalizados y automatizaciones complejas, Home Assistant escala según tus necesidades.

Recuerda mantener tu instalación actualizada, realizar backups regulares y explorar la vasta comunidad para descubrir integraciones y automatizaciones que transformarán tu hogar. El futuro de la domótica es local, privado y de código abierto, y Home Assistant Docker Compose pone todo ese poder en tus manos.

¿Listo para dar el siguiente paso? Consulta nuestra guía sobre Immich Docker Compose para complementar tu hogar inteligente con una galería fotográfica privada que preserve tus recuerdos familiares.

Home Assistant Docker Compose: Automatiza tu Casa Inteligente 2025