Home Assistant es el cerebro de un hogar conectado que funciona sin nube: controla luces, enchufes, sensores y termostatos desde tu propio servidor, y tus datos nunca salen de casa. La forma más ligera de tenerlo si ya usas Docker es la llamada Home Assistant Container: un único contenedor con la plataforma completa. En esta guía la levantas con Docker Compose en modo de red host, haces el primer arranque y el onboarding, integras dispositivos y configuras copias de seguridad. También verás con claridad qué renuncias al elegir esta vía frente a Home Assistant OS. La misma explicación está disponible en inglés.

Puntos clave

  • Home Assistant es una plataforma de domótica local, de código abierto con licencia Apache-2.0, escrita en Python y con unas 89.300 estrellas en GitHub desde su primera versión en 2013.
  • Se publica una versión nueva cada mes con el formato AÑO.MES.parche; la última estable en el momento de escribir esto es la 2026.7.2. La imagen oficial es ghcr.io/home-assistant/home-assistant.
  • Home Assistant Container es la instalación en Docker: no incluye el Supervisor ni la tienda de complementos, así que servicios como Zigbee2MQTT o ESPHome se ejecutan como contenedores aparte.
  • Necesita Docker Engine 23.0.0 o superior y se recomienda network_mode: host para que el descubrimiento de dispositivos por mDNS funcione en tu red local.
  • La interfaz web escucha en el puerto 8123; toda la configuración vive en la carpeta /config, que es lo único que necesitas respaldar.

¿Qué es Home Assistant Container?

Home Assistant es una plataforma de automatización del hogar que se ejecuta en tu propio hardware. Su documentación resume la idea así: "Home Assistant funciona en tu propio hardware, de modo que tu hogar inteligente sigue funcionando aunque se caiga Internet y tus datos se quedan en casa contigo". Reúne bajo un mismo panel cientos de marcas de dispositivos (luces, enchufes, cámaras, sensores, altavoces) y te deja crear automatizaciones sin depender de la nube de cada fabricante.

Hay varias formas de instalarlo, y la diferencia importa. Home Assistant OS es un sistema operativo completo que se instala en un miniPC o una Raspberry Pi y trae el Supervisor y la tienda de complementos; es el método recomendado para la mayoría. Home Assistant Container es lo contrario: un solo contenedor Docker con la aplicación, pensado para quien ya tiene un servidor con Docker y prefiere gestionarlo todo con docker compose. La contrapartida es clara y conviene entenderla antes de empezar: la documentación oficial avisa de que "las instalaciones de Home Assistant Container no tienen acceso a los complementos".

Eso significa que no tendrás el instalador de un clic para add-ons como Zigbee2MQTT, ESPHome, el broker MQTT Mosquitto o un router de borde Thread. Todo eso sigue siendo posible, pero lo levantas tú como contenedores independientes junto a Home Assistant. A cambio ganas control total sobre versiones, volúmenes y recursos, y encaja de forma natural en un homelab que ya orquestas con Compose. Si vienes de cero, empieza por la guía de cómo instalar Docker en Ubuntu 24.04.

¿Cómo es el docker-compose.yml en modo network host?

Home Assistant no necesita una base de datos externa para empezar: guarda su estado en una base SQLite dentro de la carpeta de configuración, así que basta un servicio y un volumen. Crea una carpeta para el proyecto y guarda dentro este docker-compose.yml. Se fija la versión 2026.7.2 en lugar de :latest, porque una etiqueta flotante puede cambiar de versión en un simple reinicio y dejarte sin control sobre lo que corres:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:2026.7.2
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      TZ: Europe/Madrid
    volumes:
      - ./config:/config
      - /run/dbus:/run/dbus:ro
      - /etc/localtime:/etc/localtime:ro

La clave de esta configuración es network_mode: host, que conecta el contenedor directamente a la red del servidor sin la capa de puente de Docker. Home Assistant lo necesita porque descubre muchos dispositivos por mDNS y difusión (Chromecast, HomeKit, impresoras, bombillas), y el modo puente bloquea ese tráfico. Si quieres repasar las diferencias, tienes la guía de redes en Docker: bridge, host y personalizadas. El privileged: true y el montaje de /run/dbus dan acceso al hardware, algo que necesitarás si conectas un adaptador USB de Zigbee o Z-Wave o el Bluetooth del equipo.

El volumen ./config:/config es el corazón del sistema: ahí se guarda configuration.yaml, la base de datos, los secretos y todo lo demás. Es un bind mount a una carpeta del host, de forma que la configuración sobrevive a cualquier recreación del contenedor; si quieres entender bien esta distinción, repasa volúmenes y bind mounts en Docker.

¿Cómo es el primer arranque y el onboarding?

Arranca el servicio y sigue los registros mientras carga por primera vez, que puede tardar un par de minutos en generar la configuración inicial:

mkdir -p homeassistant/config && cd homeassistant
docker compose up -d
docker compose logs -f homeassistant

Cuando en los registros aparezca que ha iniciado, abre en el navegador http://IP-DEL-SERVIDOR:8123. Verás el asistente de onboarding: crea tu cuenta de administrador (esta cuenta es solo tuya y local, no una cuenta en la nube), pon un nombre a tu casa y ajusta la ubicación, la zona horaria y las unidades. Home Assistant usa la ubicación para calcular el amanecer y el anochecer, que son disparadores muy habituales en las automatizaciones.

Al terminar el asistente, Home Assistant ya habrá detectado varios dispositivos y servicios de tu red gracias al modo host, y te los ofrecerá para añadirlos con un par de clics. Si más adelante quieres exponerlo en Internet con un dominio y HTTPS, ponlo detrás de un proxy inverso como se explica en cómo instalar Traefik con Docker Compose; como el contenedor usa la red del host, apunta el proxy a IP-DEL-SERVIDOR:8123 y añade en configuration.yaml la sección http: con use_x_forwarded_for y trusted_proxies.

¿Cómo integra y descubre los dispositivos?

En Home Assistant, cada marca o protocolo se conecta mediante una integración. Ve a Ajustes > Dispositivos y servicios y verás dos zonas: los dispositivos que ya se han descubierto solos (esperando tu confirmación) y el botón para añadir integración manualmente buscando por nombre. El descubrimiento automático es la gran ventaja del modo host: sin él, la mayoría de estos dispositivos no aparecerían.

Para los protocolos de radio necesitas hardware y, aquí, un matiz propio del modo Container. Un adaptador USB de Zigbee o Z-Wave se conecta con la integración nativa ZHA o con Z-Wave JS; como no dispones del complemento de un clic, el servidor de Z-Wave JS lo levantas como otro contenedor y lo enlazas por su dirección de red. La documentación lo dice sin rodeos: "Algunas integraciones, como Thread y Z-Wave, se controlan mediante complementos. No hay soporte inmediato para estas en las instalaciones Container". Para pasar el adaptador USB al contenedor, añade en el Compose un bloque devices: con la ruta del dispositivo, por ejemplo /dev/ttyUSB0:/dev/ttyUSB0.

Cuando una automatización deba avisarte fuera de casa, Home Assistant tiene su propia app móvil con notificaciones push, pero también puedes encaminar los avisos a un servidor propio como el de ntfy mediante una simple llamada HTTP desde una automatización.

¿Cómo hacer copias de seguridad de la configuración?

Todo lo que importa vive en la carpeta /config, así que respaldarla es respaldar tu instalación entera. La forma más sencilla y sin depender de nada es parar el contenedor y copiar la carpeta:

docker compose stop homeassistant
tar czf ha-config-$(date +%F).tar.gz config
docker compose start homeassistant

Desde la versión 2025.1, Home Assistant incorpora un sistema de copias de seguridad integrado que funciona también en la instalación Container. En Ajustes > Sistema > Copias de seguridad puedes crear copias cifradas, programarlas de forma automática y descargar la clave de emergencia. Genera un archivo .tar dentro de /config/backups que puedes bajar o enviar a un recurso de red. Programa una copia semanal y guarda al menos una fuera del servidor.

Actualizar es igual de sencillo, y por eso conviene tener siempre una copia reciente antes de hacerlo. Descarga la nueva imagen y recrea el contenedor; después limpia las imágenes viejas:

docker compose pull
docker compose up -d
docker image prune -f

Para saltar a una versión nueva mayor con seguridad, cambia el número de versión fijado en el docker-compose.yml en lugar de usar :latest, lee primero las notas de la versión por si hay cambios que rompan compatibilidad, y ten a mano la copia por si necesitas volver atrás.

Preguntas frecuentes

¿Puedo usar complementos (add-ons) con Home Assistant Container?

No directamente. Los complementos son una función del Supervisor, que solo está en Home Assistant OS y en la instalación Supervised. En la instalación Container no existe esa tienda de un clic. La buena noticia es que casi todos los complementos populares (Mosquitto, Zigbee2MQTT, ESPHome, Node-RED) son a su vez imágenes de Docker, así que los ejecutas como contenedores independientes en el mismo servidor y los conectas a Home Assistant. Ganas control a cambio de configurar cada uno a mano.

¿Por qué se recomienda network_mode: host en lugar de mapear el puerto 8123?

Porque Home Assistant descubre muchos dispositivos por mDNS y por difusión en la red local, y ese tráfico no atraviesa la red de puente que Docker crea por defecto. Con el modo host, el contenedor comparte la pila de red del servidor y ve la red igual que la vería el propio sistema, de modo que Chromecast, HomeKit, impresoras o bombillas aparecen solos. El efecto secundario es que no necesitas la clave ports:, porque el 8123 ya queda expuesto en la IP del host.

¿Necesito una base de datos externa como PostgreSQL o MariaDB?

No para empezar. Home Assistant guarda su histórico en una base SQLite dentro de /config, y con eso funciona perfectamente en una instalación doméstica. Solo tiene sentido pasar a MariaDB o PostgreSQL cuando registras muchísimas entidades y la base SQLite empieza a crecer o a ralentizar el panel de historial; en ese caso levantas la base como otro contenedor y ajustas la integración recorder en configuration.yaml.

Conclusión

Home Assistant Container es la vía ideal para tener domótica local completa si ya administras un servidor con Docker. Con un único docker-compose.yml en modo host levantas la plataforma, haces el onboarding en el puerto 8123 y empiezas a integrar dispositivos que el propio sistema descubre en tu red. A cambio de renunciar al Supervisor y a la tienda de complementos, ganas control total sobre versiones y recursos, y encajas Home Assistant en el resto de tu homelab. El siguiente paso es programar copias de seguridad de la carpeta /config y, si vas a exponerlo, ponerlo tras un proxy inverso con HTTPS. Si en cambio buscas la experiencia más sencilla con complementos de un clic, valora instalar Home Assistant OS en un equipo dedicado.

Fuentes

  1. Documentación oficial de Home Assistant: instalación en Linux
  2. Home Assistant: comparación de métodos de instalación
  3. Home Assistant: tareas comunes en Container
  4. Repositorio oficial home-assistant/core en GitHub
  5. Imagen homeassistant/home-assistant en Docker Hub

Ruta: Redes y acceso remoto seguro con Docker