---
title: "Cómo instalar Home Assistant en Ubuntu 24.04 con Docker"
description: "Instala Home Assistant en Ubuntu 24.04 con Docker Compose, publícalo tras Nginx con HTTPS de Let's Encrypt y completa la configuración inicial de forma segura."
category: "Automatización del Hogar e IoT"
language: es
source: https://cubepath.com/es/docs/automatización-del-hogar-e-iot/instalacion-de-home-assistant-en-linux
updated: 2026-09-25
---

# Cómo instalar Home Assistant en Ubuntu 24.04 con Docker

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.

> Nota: Home Assistant Container es el método de instalación adecuado para un servidor genérico. No incluye el Supervisor ni la tienda de complementos (add-ons); los servicios auxiliares, como un broker MQTT, se instalan aparte. Además, en un servidor remoto no hay acceso a hardware local (USB Zigbee, Bluetooth) ni descubrimiento de dispositivos en tu red de casa, así que esta instalación es útil sobre todo para integraciones en la nube, MQTT y dispositivos que se conectan a través de una VPN.

## 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:

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

Crea el archivo de Compose:

```bash
nano ~/homeassistant/compose.yaml
```

```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:

```bash
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:

```bash
docker compose logs -f homeassistant
```

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

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

```output
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`):

```bash
sudo nano ~/homeassistant/config/configuration.yaml
```

Añade al final este bloque:

```yaml
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:

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

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

```bash
docker compose restart homeassistant
```

## Paso 4: Configurar Nginx como proxy inverso

Instala Nginx y Certbot con su plugin para Nginx:

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

Crea el sitio para Home Assistant:

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

```nginx
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:

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

```output
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:

```bash
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:

```bash
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:

```bash
sudo certbot renew --dry-run
```

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

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

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

```output
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`:

```bash
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**.