Instalación de Home Assistant

Qué configuramos y por qué

Home Assistant es una potente plataforma de código abierto para la automatización del hogar inteligente, que prioriza la privacidad y el control local. Permite unificar dispositivos de diferentes fabricantes en un solo sistema, crear automatizaciones complejas, monitorear el estado de los sensores y gestionar todos los aspectos de su hogar desde una interfaz unificada.

En esta guía, implementaremos Home Assistant en un servidor privado virtual (VPS). Esta solución ofrece varias ventajas clave:

• Control total y privacidad: Sus datos permanecen en su servidor. No depende de los servicios en la nube ni de sus políticas de privacidad.
• Flexibilidad y escalabilidad: Un VPS proporciona significativamente más recursos que las computadoras de placa única como Raspberry Pi, lo que permite manejar más integraciones, automatizaciones y almacenar un mayor volumen de datos sin sacrificar el rendimiento.
• Fiabilidad 24/7: Los VPS suelen alojarse en centros de datos profesionales con alta disponibilidad y una conexión a internet estable, lo que garantiza el funcionamiento ininterrumpido de su sistema de hogar inteligente.
• Acceso remoto: Configuraremos un acceso seguro a Home Assistant desde cualquier parte del mundo a través de un nombre de dominio y HTTPS, protegido por un certificado SSL.

Como alternativas a Home Assistant en un VPS, se pueden considerar:

• Home Assistant Green/Yellow o Raspberry Pi: Una solución local, fácil de implementar, pero limitada en recursos y que requiere alimentación constante y conexión a internet en su hogar.
• Plataformas de hogar inteligente en la nube (Google Home, Amazon Alexa, Apple HomeKit): Convenientes, pero a menudo requieren la transferencia de sus datos a sus servidores y limitan el control sobre los dispositivos.
• Soluciones gestionadas (por ejemplo, Home Assistant Cloud): Ofrecen acceso remoto conveniente e integración con asistentes de voz por una tarifa de suscripción, pero aún dependen de un servicio de terceros.

La elección de una solución autoalojada en un VPS permite combinar las ventajas del control local con la fiabilidad y el rendimiento de la infraestructura en la nube, lo que la hace ideal para usuarios avanzados y aquellos que valoran la privacidad.

Qué configuración de VPS se necesita para esta tarea

La elección de una configuración de VPS adecuada es crucial para el funcionamiento estable y rápido de Home Assistant, especialmente a medida que crece su sistema de hogar inteligente.

Requisitos mínimos (para instalaciones pequeñas, hasta 20-30 dispositivos/integraciones)

• CPU: 2 núcleos (arquitectura x86-64)
• RAM: 4 GB (Home Assistant puede ser exigente con la memoria, especialmente con la base de datos y muchas adiciones)
• Disco: 80 GB SSD (un disco rápido es importante para la base de datos de Home Assistant y el acceso rápido a los archivos; 80 GB proporcionan espacio para registros, copias de seguridad y el crecimiento de la base de datos)
• Red: 100 Mbit/s (suficiente para acceso remoto y actualizaciones)
• Sistema operativo: Ubuntu Server 24.04 LTS (recomendado)

Plan de VPS recomendado (para instalaciones medianas y grandes, más de 50 dispositivos, cámaras, asistentes de voz)

• CPU: 4 núcleos
• RAM: 8 GB
• Disco: 160 GB SSD (con espacio para datos a largo plazo, historial y posibles imágenes Docker de otros servicios)
• Red: 1 Gbit/s (para descargas rápidas, transmisión de video desde cámaras)
• Sistema operativo: Ubuntu Server 24.04 LTS

Para alquilar un VPS con estas características, puede considerar un VPS con las características indicadas, adecuado para un alojamiento fiable de Home Assistant.

Cuándo se necesita un servidor dedicado y no un VPS

Un servidor dedicado puede ser necesario en casos raros si:

• Planea una instalación muy grande de Home Assistant (cientos de dispositivos, decenas de cámaras IP con procesamiento de video).
• Necesita absolutamente todos los recursos del servidor sin virtualización.
• Desea alojar en el servidor muchas otras aplicaciones que consumen muchos recursos además de Home Assistant.
• Se requiere hardware específico no disponible en un VPS (por ejemplo, GPU para tareas de IA).

En la mayoría de los casos, un VPS bien configurado es suficiente para Home Assistant. Si su proyecto requiere el máximo rendimiento y control total sobre el hardware, puede considerar un servidor dedicado adecuado.

Ubicación: en qué influye

La elección de la ubicación del servidor VPS puede influir en varios aspectos:

• Latencia: Si planea usar Home Assistant para controlar dispositivos que requieren una latencia mínima (por ejemplo, para una reacción instantánea a los sensores), es mejor elegir un servidor geográficamente cercano a usted o a su hogar. Sin embargo, para la mayoría de las automatizaciones y el acceso remoto, una latencia de 50-150 ms no será crítica.
• Legislación: Dependiendo de sus preferencias de privacidad y almacenamiento de datos, puede elegir una jurisdicción que cumpla con sus requisitos.
• Precio: Los precios de los VPS pueden variar según la ubicación del centro de datos.

Para Home Assistant, que funciona con dispositivos en su hogar, la principal importancia radica en una conexión a internet estable y suficientemente rápida entre su hogar y el VPS. La proximidad geográfica a sus dispositivos físicos de hogar inteligente tiene menos importancia, ya que la mayoría de las integraciones modernas de Home Assistant utilizan llamadas a la API y no un acceso local directo a los dispositivos, a menos que configure puentes locales específicos.

Preparación del servidor

Antes de instalar Home Assistant, es necesario realizar la configuración básica y la protección de su VPS. Utilizaremos Ubuntu Server 24.04 LTS como un sistema operativo estable y ampliamente utilizado.

1. Conexión por SSH

Conéctese a su nuevo VPS usando SSH. Necesitará la dirección IP del servidor y las credenciales (normalmente el usuario root y la contraseña, o una clave SSH).

ssh root@ВАШ_IP_АДРЕС_VPS

2. Creación de un nuevo usuario y configuración de sudo

Trabajar como usuario root no es seguro. Crearemos un nuevo usuario y lo añadiremos al grupo sudo.

# Reemplace 'su_usuario' con el nombre de usuario deseado
adduser ваш_пользователь
usermod -aG sudo ваш_пользователь

Ahora, salga de la sesión root e inicie sesión con el nuevo usuario:

exit
ssh ваш_пользователь@ВАШ_IP_АДРЕС_VPS

3. Configuración de la autenticación por claves SSH (recomendado)

Si aún no utiliza claves SSH, esta es la forma más segura de autenticación. Genere las claves en su máquina local, si no las tiene:

# En su máquina LOCAL
ssh-keygen -t ed25519 -C "ваша_почта@example.com"

Copie la clave pública al servidor:

# En su máquina LOCAL
ssh-copy-id ваш_пользователь@ВАШ_IP_АДРЕС_VPS

Después de copiar con éxito, desactive el inicio de sesión con contraseña para root y su nuevo usuario. Edite el archivo de configuración del servidor SSH:

sudo nano /etc/ssh/sshd_config

Busque y modifique las siguientes líneas (o añádalas, si no existen):

# Desactivamos el inicio de sesión con contraseña
PasswordAuthentication no
# Desactivamos el inicio de sesión para root
PermitRootLogin no

Reinicie el servicio SSH:

sudo systemctl restart sshd

4. Actualización del sistema

Siempre comience actualizando la base de paquetes y los paquetes instalados.

sudo apt update && sudo apt upgrade -y

5. Configuración del firewall (UFW)

UFW (Uncomplicated Firewall) es una interfaz fácil de usar para iptables. Lo configuraremos para permitir solo los puertos necesarios.

# Instalamos UFW, si no está instalado
sudo apt install ufw -y

# Permitimos SSH (puerto 22)
sudo ufw allow ssh

# Permitimos HTTP (puerto 80) y HTTPS (puerto 443) para acceso web y Let's Encrypt
sudo ufw allow http
sudo ufw allow https

# Permitimos el puerto de Home Assistant (normalmente 8123), si se planea acceso directo sin proxy
# Sin embargo, usaremos Caddy como proxy inverso, por lo que este puerto puede dejarse cerrado desde el exterior
# sudo ufw allow 8123/tcp

# Habilitamos el firewall
sudo ufw enable

Confirme que desea continuar si UFW advierte sobre una posible interrupción de la conexión SSH. Verifique el estado:

sudo ufw status verbose

6. Instalación de Fail2Ban

Fail2Ban escanea los registros y bloquea las direcciones IP que muestran signos de ataques maliciosos (por ejemplo, múltiples intentos fallidos de inicio de sesión SSH).

sudo apt install fail2ban -y
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Cree un archivo de configuración local para Fail2Ban para que sus cambios no sean sobrescritos al actualizar el paquete:

sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo nano /etc/fail2ban/jail.local

En el archivo jail.local, asegúrese de que la sección [sshd] esté activa (enabled = true) y, si es necesario, configure bantime (tiempo de bloqueo) y maxretry (número de intentos).

# Ejemplo de sección sshd en jail.local
[sshd]
enabled = true
port = ssh
logpath = %(sshd_log)s
backend = %(sshd_backend)s
# bantime = 1d # Bloquear por 1 día
# maxretry = 3 # Bloquear después de 3 intentos fallidos

Guarde los cambios y reinicie Fail2Ban:

sudo systemctl restart fail2ban

7. Instalación de utilidades básicas

Instalaremos algunas utilidades útiles que serán de ayuda durante el proceso de instalación y mantenimiento.

sudo apt install curl wget git htop ntpdate -y

ntpdate ayudará a sincronizar la hora del sistema, lo cual es importante para el funcionamiento de los certificados SSL y muchos servicios de red. En las versiones modernas de Ubuntu, systemd-timesyncd ya suele estar activo y es bastante eficiente.

# Verificación del estado de sincronización de la hora
timedatectl status

Instalación de software — paso a paso

Ahora que el servidor está preparado, procederemos con la instalación de Docker, Docker Compose, Home Assistant y un proxy inverso con SSL.

1. Instalación de Docker Engine (válido para el año 2026)

Instalaremos Docker desde el repositorio oficial de Docker para obtener las versiones más recientes.

# Обновляем список пакетов
sudo apt update

# Устанавливаем необходимые пакеты для установки Docker из репозитория
sudo apt install ca-certificates curl gnupg lsb-release -y

# Добавляем официальный GPG ключ Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Добавляем репозиторий Docker в APT источники
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Обновляем список пакетов с учетом нового репозитория Docker
sudo apt update

# Устанавливаем Docker Engine, Docker CLI и containerd
sudo apt install docker-ce docker-ce-cli containerd.io -y

# Проверяем статус Docker
sudo systemctl status docker

Añadimos nuestro usuario al grupo docker para ejecutar comandos de Docker sin sudo (será necesario reconectarse a SSH).

# Замените 'ваш_пользователь' на ваше имя пользователя
sudo usermod -aG docker ваш_пользователь

# Переподключитесь к SSH, чтобы изменения вступили в силу
exit
ssh ваш_пользователь@ВАШ_IP_АДРЕС_VPS

Verifique que Docker funciona ejecutando un contenedor de prueba:

docker run hello-world

2. Instalación del plugin Docker Compose

En las versiones modernas, Docker Compose es un plugin de Docker CLI. Lo instalamos:

sudo apt install docker-compose-plugin -y

# Проверяем версию Docker Compose
docker compose version

3. Preparación de la estructura de directorios para Home Assistant

Crearemos un directorio donde se almacenarán los archivos de configuración de Home Assistant y docker-compose.yml.

mkdir ~/homeassistant
cd ~/homeassistant

4. Creación del archivo docker-compose.yml para Home Assistant

Cree el archivo docker-compose.yml. En él definiremos el servicio Home Assistant, sus puertos, volúmenes para el almacenamiento de datos y la política de reinicio.

nano docker-compose.yml

Pegue el siguiente contenido:

# Версия Docker Compose файла
version: '3'

# Определяем сервисы
services:
  homeassistant:
    # Используем официальный образ Home Assistant Core
    # Актуальный образ для 2026 года будет 'homeassistant/home-assistant:stable' или 'homeassistant/home-assistant:2026.x.x'
    image: homeassistant/home-assistant:stable
    # Название контейнера
    container_name: homeassistant
    # Указываем, какие порты контейнера маппировать на хост
    # Порт 8123 - стандартный порт Home Assistant
    # Мы маппируем его на локальный порт 8123, который будет доступен только внутри VPS
    # Доступ извне будет через Caddy (обратный прокси)
    ports:
      - "127.0.0.1:8123:8123"
    # Тома для сохранения данных Home Assistant
    # /path/to/your/config:/config - замените на актуальный путь на вашем VPS
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    # Разрешаем контейнеру доступ к хост-сети для обнаружения устройств
    # network_mode: host # Можно использовать, но тогда порт 8123 будет открыт на всех интерфейсах VPS
    # Лучше использовать bridge network и настроить trusted_proxies в HA
    # Перезапускать контейнер автоматически, если он остановился
    restart: unless-stopped
    # Установка временной зоны
    environment:
      TZ: Europe/Moscow # Или ваша временная зона

Guarde el archivo (Ctrl+O, Enter, Ctrl+X).

5. Inicio de Home Assistant

Inicie el contenedor de Home Assistant usando Docker Compose:

docker compose up -d

Verifique el estado del contenedor:

docker compose ps
docker logs homeassistant

El primer inicio de Home Assistant puede tardar varios minutos mientras carga todos los componentes necesarios.

6. Instalación y configuración de Caddy (proxy inverso con auto-SSL)

Caddy es un potente servidor web que gestiona automáticamente los certificados SSL de Let's Encrypt. Es ideal para nuestro caso.

6.1. Adición del repositorio de Caddy

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update

6.2. Instalación de Caddy

sudo apt install caddy -y

6.3. Configuración de Caddyfile

Cree o edite el archivo de configuración de Caddy. Asegúrese de tener un nombre de dominio (por ejemplo, ha.yourdomain.com) que apunte a la dirección IP de su VPS.

sudo nano /etc/caddy/Caddyfile

Elimine todo el contenido existente y pegue lo siguiente, reemplazando ha.yourdomain.com por su dominio real:

# Ваш домен для Home Assistant
ha.yourdomain.com {
    # Включаем автоматическую выдачу и обновление SSL-сертификата Let's Encrypt
    tls [email protected]

    # Обратный прокси к Home Assistant, запущенному на локальном порту 8123
    reverse_proxy 127.0.0.1:8123 {
        # Заголовки, необходимые для корректной работы WebSocket и удаленного IP
        header_up Host {host}
        header_up X-Real-IP {remote_ip}
        header_up X-Forwarded-For {remote_ip}
        header_up X-Forwarded-Proto {scheme}
    }

    # Включаем сжатие, если необходимо (опционально)
    # encode gzip zstd

    # Логирование (опционально)
    # log {
    #     output file /var/log/caddy/ha_access.log
    # }
}

Guarde el archivo (Ctrl+O, Enter, Ctrl+X).

6.4. Verificación e inicio de Caddy

# Проверяем синтаксис Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile

# Перезапускаем сервис Caddy, чтобы применить изменения
sudo systemctl reload caddy

# Проверяем статус Caddy
sudo systemctl status caddy

Asegúrese de que Caddy se ha iniciado correctamente y ha obtenido el certificado SSL. Esto puede tardar unos segundos.

Configuración

Después de instalar Home Assistant y configurar el proxy inverso, es necesario realizar la configuración inicial de Home Assistant para que funcione correctamente a través del nombre de dominio y SSL.

1. Configuración inicial de Home Assistant

Abra su navegador y vaya a https://ha.yourdomain.com (reemplace por su dominio). Debería ver la página de bienvenida de Home Assistant.

1. Cree una cuenta de propietario: Introduzca un nombre, usuario y contraseña para el primer usuario. Esta será su cuenta administrativa principal.
2. Configure la ubicación: Especifique su ubicación, zona horaria y unidades de medida. Esto es importante para el correcto funcionamiento de muchas integraciones y automatizaciones (por ejemplo, para el amanecer/atardecer).
3. Detección de dispositivos: Home Assistant intentará detectar automáticamente algunos dispositivos en su red local. Dado que Home Assistant funciona en Docker en un VPS, no verá directamente la red local de su hogar. Deberá añadir dispositivos manualmente o a través de otros puentes/pasarelas.
4. Complete la configuración: Accederá al panel principal de Home Assistant.

2. Configuración de Home Assistant para funcionar a través de un proxy inverso

Para que Home Assistant funcione correctamente a través de un proxy inverso (Caddy), es necesario informarle sobre los proxies de confianza y habilitar el uso de los encabezados X-Forwarded-For.

Conéctese a su VPS y vaya al directorio de configuración de Home Assistant:

cd ~/homeassistant/config
nano configuration.yaml

Añada las siguientes líneas a configuration.yaml:

# Базовая конфигурация Home Assistant
homeassistant:
  # Если вы используете домен ha.yourdomain.com
  external_url: "https://ha.yourdomain.com"
  internal_url: "http://127.0.0.1:8123" # Внутренний адрес, доступный только на VPS

# Доверенные прокси
http:
  use_x_forwarded_for: true
  # IP-адрес вашего VPS. Это важно, чтобы Home Assistant доверял запросам от Caddy.
  # Если Caddy запущен на том же хосте, что и Home Assistant, используйте 172.17.0.1 (IP Docker-моста)
  # или подсеть Docker, если у вас сложная конфигурация сети.
  # Для простоты, если Caddy на том же хосте, можно использовать IP-адрес вашего VPS
  # или рассмотреть использование IP-адреса Docker-моста.
  # На Ubuntu с Docker по умолчанию, IP Docker-моста часто 172.17.0.1
  # Проверить можно командой: docker network inspect bridge
  trusted_proxies:
    - 172.17.0.0/16 # Пример: вся подсеть Docker-моста
    # Или конкретный IP, если Caddy не в Docker или на другом хосте:
    # - ВАШ_IP_АДРЕС_VPS

Guarde el archivo (Ctrl+O, Enter, Ctrl+X).

Para que los cambios surtan efecto, reinicie el contenedor de Home Assistant:

cd ~/homeassistant
docker compose restart homeassistant

Espere a que se reinicie completamente (1-2 minutos), luego actualice la página de Home Assistant en el navegador.

3. Uso de secretos (secrets.yaml)

Para almacenar datos sensibles, como claves API, contraseñas, tokens, se recomienda encarecidamente usar el archivo secrets.yaml. Nunca los guarde directamente en configuration.yaml.

En configuration.yaml, se hace referencia a un secreto de la siguiente manera:

# Пример в configuration.yaml
sensor:
  - platform: template
    sensors:
      my_secret_api_key: !secret my_api_key

Y luego cree el archivo secrets.yaml en el mismo directorio ~/homeassistant/config/:

nano ~/homeassistant/config/secrets.yaml

Y añada el secreto allí:

# Пример в secrets.yaml
my_api_key: "ваш_очень_секретный_ключ"
my_password: "мой_супер_пароль_123"

Asegúrese de que los permisos de acceso a secrets.yaml estén restringidos:

chmod 600 ~/homeassistant/config/secrets.yaml

4. Verificación de la operatividad

Después de todas las configuraciones, asegúrese de que todo funciona correctamente:

• Acceso por HTTPS: Abra https://ha.yourdomain.com en el navegador. Asegúrese de ver el candado verde y ninguna advertencia de seguridad.
• Verificación del certificado SSL: En el navegador, compruebe los detalles del certificado (quién lo emitió, fecha de caducidad).
• Verificación de la conexión WebSocket: Home Assistant utiliza activamente WebSocket. Abra el panel de desarrollador en el navegador (F12), la pestaña "Network" y asegúrese de que no haya errores de WebSocket.
• Verificación de los registros de Home Assistant: Asegúrese de que no haya errores críticos relacionados con la red o el proxy.

cd ~/homeassistant
docker compose logs homeassistant

¡Ha configurado Home Assistant con éxito en un VPS con acceso seguro a través de HTTPS!