Home Assistant es una plataforma de domótica de código abierto que centraliza dispositivos, servicios en la nube y automatizaciones en un único panel. En este tutorial instalarás Home Assistant Container con Docker Compose en Ubuntu 24.04, lo publicarás en tu dominio detrás de Nginx con un certificado de Let's Encrypt y completarás el asistente inicial. Al terminar podrás acceder a tu instancia desde cualquier lugar por HTTPS.

Requisitos previos

  • Un servidor con Ubuntu 24.04 LTS con al menos 2 GB de RAM y 2 vCPU, por ejemplo un VPS de CubePath.
  • Un usuario no root con privilegios sudo.
  • Docker Engine y el plugin de Docker Compose instalados desde el repositorio oficial de Docker.
  • Un dominio o subdominio (en esta guía your_domain) con un registro DNS A apuntando a la IP de tu servidor.
  • UFW activo con SSH permitido.

Paso 1: Crear el proyecto de Docker Compose

Crea un directorio para Home Assistant con una subcarpeta config, donde se guardarán la configuración, la base de datos y las copias de seguridad:

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

Crea el archivo de Compose:

nano ~/homeassistant/compose.yaml

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    network_mode: host

Home Assistant usa network_mode: host porque muchas integraciones necesitan ver la red directamente. Con red de host, el contenedor escucha en el puerto 8123 del servidor y, a diferencia de los puertos publicados con ports:, UFW sí filtra ese tráfico. No abrirás el 8123 en el firewall: todo el acceso externo pasará por Nginx.

Paso 2: Arrancar Home Assistant

Descarga la imagen y arranca el contenedor en segundo plano:

docker compose up -d

El primer arranque tarda uno o dos minutos mientras se crea la configuración inicial. Sigue el log hasta que se estabilice:

docker compose logs -f homeassistant

Pulsa Ctrl+C para salir del log. Comprueba que responde en local:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8123/manifest.json

200

En ~/homeassistant/config ya existe el archivo configuration.yaml que editarás en el siguiente paso.

Paso 3: Permitir el proxy inverso en Home Assistant

Por seguridad, Home Assistant rechaza las peticiones que llegan a través de un proxy si no confías explícitamente en él, y responde con un error 400. Edita la configuración (el contenedor crea los archivos como root, por eso usas sudo):

sudo nano ~/homeassistant/config/configuration.yaml

Añade al final este bloque:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1

use_x_forwarded_for hace que Home Assistant registre la IP real del cliente y trusted_proxies limita esa confianza al Nginx que corre en el propio servidor.

Valida la configuración antes de reiniciar:

docker exec homeassistant python -m homeassistant --script check_config --config /config

Si no aparece ningún error en la salida, reinicia el contenedor:

docker compose restart homeassistant

Paso 4: Configurar Nginx como proxy inverso

Instala Nginx y Certbot con su plugin para Nginx:

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx

Crea el sitio para Home Assistant:

sudo nano /etc/nginx/sites-available/homeassistant

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    listen [::]:80;
    server_name your_domain;

    location / {
        proxy_pass http://127.0.0.1:8123;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }
}

Las cabeceras Upgrade y Connection son imprescindibles: la interfaz de Home Assistant se comunica con el servidor mediante WebSocket en /api/websocket y, sin ellas, la página carga pero se queda en "Conectando".

Activa el sitio, desactiva el sitio por defecto y comprueba la sintaxis:

sudo ln -s /etc/nginx/sites-available/homeassistant /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Recarga Nginx y abre HTTP y HTTPS en el firewall:

sudo systemctl reload nginx
sudo ufw allow 'Nginx Full'

Paso 5: Obtener el certificado TLS

Solicita el certificado con Certbot. El plugin de Nginx añade automáticamente el bloque listen 443 ssl y la redirección de HTTP a HTTPS:

sudo certbot --nginx -d your_domain

Certbot instala también un temporizador de systemd que renueva el certificado antes de que caduque. Comprueba que la renovación funciona:

sudo certbot renew --dry-run

Congratulations, all simulated renewals succeeded:
  /etc/letsencrypt/live/your_domain/fullchain.pem (success)

Verifica que Home Assistant responde a través del dominio:

curl -s -o /dev/null -w '%{http_code}\n' https://your_domain/manifest.json

200

Paso 6: Completar la configuración inicial

Abre https://your_domain en el navegador. El asistente de bienvenida te pedirá:

  1. Crear la cuenta de propietario (nombre, usuario y contraseña). Usa una contraseña robusta: esta instancia es accesible desde Internet.
  2. Indicar la ubicación de tu casa, la zona horaria y el sistema de unidades.
  3. Decidir si compartes datos de uso anónimos.
  4. Revisar las integraciones detectadas y terminar.

Una vez dentro, activa la autenticación en dos pasos desde tu perfil (esquina inferior izquierda, sección Seguridad, módulo de autenticación multifactor). Es la medida más eficaz para proteger una instancia expuesta a Internet.

Gracias a use_x_forwarded_for, los avisos de inicios de sesión fallidos mostrarán la IP pública del cliente y no 127.0.0.1.

Paso 7: Añadir integraciones

Las integraciones se añaden desde Ajustes > Dispositivos y servicios > Añadir integración. La mayoría ya no se configuran en configuration.yaml, sino desde este asistente.

Si vas a usar MQTT para sensores propios (ESP32, Tasmota, Zigbee2MQTT en otro equipo), instala antes un broker como Mosquitto en el servidor y después añade la integración MQTT indicando 127.0.0.1, el puerto 1883 y el usuario del broker. Home Assistant creará las entidades de los dispositivos que publiquen mensajes de descubrimiento.

Actualizar y hacer copias de seguridad

Para actualizar a la última versión estable, descarga la imagen nueva y recrea el contenedor. La configuración se conserva porque está en el volumen ./config:

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

Antes de actualizar, crea una copia desde Ajustes > Sistema > Copias de seguridad. Las copias locales se guardan en ~/homeassistant/config/backups; cópialas fuera del servidor periódicamente, por ejemplo con rsync o un bucket de almacenamiento de objetos.

Solución de problemas

400: Bad Request al entrar por el dominio: falta el bloque http: con trusted_proxies o no has reiniciado el contenedor tras añadirlo. Revisa el log con docker compose logs homeassistant | grep -i proxy.

La interfaz se queda en "Conectando" o "Unable to connect": Nginx no reenvía el WebSocket. Confirma que el bloque map y las cabeceras Upgrade y Connection están en la configuración y que sudo nginx -t no da errores.

502 Bad Gateway: el contenedor está parado o todavía arrancando. Comprueba el estado con docker compose ps y los errores con docker compose logs --tail 50 homeassistant.

Home Assistant no arranca tras editar YAML: normalmente es un error de indentación. Ejecuta el comando check_config del paso 3, corrige la línea que indica y reinicia.

Conclusión

Tienes Home Assistant ejecutándose en contenedor en Ubuntu 24.04, accesible solo por HTTPS a través de Nginx, con el puerto 8123 cerrado al exterior y actualizaciones que se reducen a dos comandos. La configuración y las copias de seguridad viven en un único directorio fácil de respaldar.

Como siguientes pasos puedes:

  • Instalar Mosquitto con autenticación y TLS para conectar sensores por MQTT.
  • Conectar la red de tu casa al servidor con WireGuard o Tailscale para integrar dispositivos locales.
  • Crear tus primeras automatizaciones desde Ajustes > Automatizaciones y escenas.