Tutoriales de VPS
Home Assistant Container en un VPS: MQTT, HTTPS y límites de LAN
Despliega Home Assistant Container con Docker y Caddy. Planifica conexiones domésticas, listeners MQTT y proxy de confianza; protege cuentas, limita historial y prueba copias coherentes antes de actualizar.

Home Assistant coordina luces, sensores, cámaras, energía y automatizaciones. Un VPS sirve para integraciones cloud y dispositivos remotos conectados deliberadamente, pero no ve automáticamente la LAN de casa. Conserva funciones esenciales cuando internet o el VPS fallen.
Usaremos Ubuntu 24.04, Docker Compose y Home Assistant Container.
- Container no tiene Supervisor ni tienda de aplicaciones/add-ons de Home Assistant OS; despliega servicios auxiliares aparte.
- Home Assistant OS incluye el entorno administrado y sirve para un equipo doméstico o VM compatible, no para instalarlo dentro de un contenedor Docker corriente.
- Supervised es un método heredado con requisitos estrictos del anfitrión; elige un método actualmente soportado para una instalación nueva.
Zigbee/Z-Wave USB y Bluetooth suelen necesitar un equipo en casa. API cloud y MQTT enrutable pueden servir desde un VPS. Matter no se vuelve remoto automáticamente: necesita conectividad IPv6/multicast local, controlador y, en algunos casos, un router de borde Thread.
| Recurso | Prueba ligera | Referencia de uso continuo |
|---|---|---|
| CPU | 2 vCPU | 2-4 vCPU |
| RAM | 2 GB | 4 GB o más |
| Disco | 30 GB SSD | 60 GB SSD o más |
| Sistema | Ubuntu 22.04/24.04 | Ubuntu 24.04 LTS |
| Dominio | ha.example.com | Subdominio de automatización |
Historial, entidades y cámaras cambian estas necesidades. Revisa free -h, df -h y docker stats; consulta dimensionamiento.
- Decide por dispositivo: API cloud, MQTT autenticado o puente compatible.
- Administra mediante HTTPS verificado o WireGuard/Tailscale privado.
- Mantén 1883 privado; publica solo un listener seguro cuando haga falta.
- Deja vídeo en la LAN o VPN apropiada, sin convertir un VPS pequeño en relay de todas las cámaras.
sudo apt update
sudo apt install -y ca-certificates curl openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/homeassistant/config
sudo chown -R "$USER":"$USER" /opt/homeassistant
cd /opt/homeassistant
Revisa el instalador root o usa paquetes soportados. El grupo Docker concede acceso potente. Conserva /config fuera del contenedor y evita editar configuration.yaml simultáneamente.
services:
homeassistant:
image: ghcr.io/home-assistant/home-assistant:stable
container_name: homeassistant
restart: unless-stopped
network_mode: host
environment:
TZ: Asia/Shanghai
volumes:
- /opt/homeassistant/config:/config
- /etc/localtime:/etc/localtime:ro
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8123/ || exit 1"]
interval: 30s
timeout: 10s
retries: 5
Asia/Shanghai es un ejemplo regional: usa tu zona IANA y configura ubicación/zona horaria durante el registro. Fija una versión exacta soportada en lugar de seguir stable sin control.
Host networking descubre dispositivos de la red del VPS, sin trasladar broadcasts domésticos. También puede exponer 8123 en interfaces del anfitrión: restringe listener/firewall. Sin descubrimiento, usa bridge y 127.0.0.1:8123:8123. Comprueba que la imagen incluye curl para su healthcheck; una sonda inválida no prueba un fallo de la aplicación.
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=150 homeassistant
ssh -L 8123:127.0.0.1:8123 root@SERVER_IP
Abre http://127.0.0.1:8123 por el túnel y crea administrador, ubicación y zona horaria.
sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile
ha.example.com {
encode gzip zstd
reverse_proxy 127.0.0.1:8123
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
}
}
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://ha.example.com
Este ajuste corresponde a Caddy en el anfitrión y aplicación con red host:
http:
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1
Combínalo con la sección http existente y valida/reinicia. Con bridge, utiliza el IP real del proxy visto por el contenedor. Nunca confíes en 0.0.0.0/0. Usa una sola puerta de entrada en 80/443 y HSTS/includeSubDomains solo con HTTPS funcional. Consulta Caddy.
Añade este servicio bajo services y prepara directorios persistentes:
mosquitto:
image: eclipse-mosquitto:2
container_name: mosquitto
restart: unless-stopped
ports:
- "127.0.0.1:1883:1883"
volumes:
- /opt/mosquitto/config:/mosquitto/config
- /opt/mosquitto/data:/mosquitto/data
- /opt/mosquitto/log:/mosquitto/log
El ejemplo antiguo necesita un cambio: un listener ligado al loopback interno del contenedor no recibe la conexión reenviada por Docker.
listener 1883 127.0.0.1
allow_anonymous false
password_file /mosquitto/config/passwd
acl_file /mosquitto/config/acl
persistence true
persistence_location /mosquitto/data/
Usa listener 1883 dentro del broker y conserva la publicación del anfitrión en 127.0.0.1 o una interfaz privada. Mantén allow_anonymous false, crea passwd con mosquitto_passwd y una ACL limitada por dispositivo. -c es solo para un archivo nuevo: sobrescribe el existente. Da a Home Assistant los temas de estado/comando/descubrimiento necesarios, sin compartir esa cuenta con todos los dispositivos. Configura permisos de lectura y escritura del usuario de la imagen.
- Home Assistant con red host conecta a 127.0.0.1:1883; DNS de servicios Docker corresponde a una red bridge compartida.
- Los dispositivos domésticos no alcanzan loopback del VPS; usa VPN/listener privado o un túnel apropiado.
- MQTT por redes no confiables necesita TLS; una contraseña no cifra tráfico.
- Comprueba DNS, rutas VPN, TCP, ACL y temas antes de cambiar configuraciones; no habilites anonimato.
- Usa integraciones cloud compatibles con HTTPS saliente.
- Mantén MQTT/Zigbee2MQTT o el puente compatible en casa y conecta al VPS.
- Enruta IP mediante WireGuard/Tailscale.
- Si necesitas multicast, configúralo explícitamente con alcance limitado; una ruta de subred no transporta mDNS/SSDP por sí sola.
Son opciones, sin clasificación universal de fiabilidad. Para radios USB, Bluetooth y cámaras/Matter muy locales, un equipo doméstico suele ser más práctico.
Empieza con un sensor y una luz:
- Comprueba tiempo de actualización.
- Verifica condiciones y zona horaria.
- Prueba desconexión/reconexión.
- Busca errores de autenticación y bucles.
- Mide crecimiento del historial.
SQLite es el recorder predeterminado. Reduce entidades/retención antes de externalizar; usa solo una base admitida por la versión y con copia propia. Guarda vídeo en NVR o almacenamiento dedicado, no en /config.
- Activa MFA y permisos compatibles; ocultar un panel no impone aislamiento por entidad.
- Cierra puertos públicos innecesarios, especialmente 8123/MQTT; expón 80/443 solo si hace falta.
- Prohíbe MQTT anónimo y separa cuentas por dispositivo.
- Protege claves cloud permanentes fuera de código expuesto.
- Restringe el panel a VPN si ese es tu diseño; Caddy público también necesita control de acceso.
- Revisa fallos de login e IP inesperados.
- Revisa origen y permisos de integraciones personalizadas.
- No publiques dirección doméstica, URL de cámaras o tokens.
Prueba WebSocket y conexiones largas, evitando caché CDN de respuestas autenticadas.
/config contiene automatizaciones, credenciales, usuarios, integraciones y normalmente historial SQLite. El siguiente comando requiere primero un estado consistente de base/configuración:
mkdir -p /opt/homeassistant/backups
tar -czf /opt/homeassistant/backups/homeassistant-$(date +%F).tgz -C /opt/homeassistant config
Para copia de archivos es más seguro detener el contenedor:
docker compose stop
tar -czf /opt/homeassistant/backups/homeassistant-safe-$(date +%F).tgz -C /opt/homeassistant config
docker compose start
Guarda además Compose, configuración/credenciales/datos MQTT y base externa cuando exista. Cifra copias externas y conserva la clave de recuperación de backups cifrados. Restaura la misma versión exacta y prueba login, integraciones, automatizaciones, MQTT e historial. Evita que una restauración de prueba accione dispositivos reales. Consulta recuperación.
docker image inspect ghcr.io/home-assistant/home-assistant:stable --format '{{.Id}}' > /opt/homeassistant/backups/image-id.txt
cp compose.yml /opt/homeassistant/backups/compose-$(date +%F).yml
docker compose pull
docker compose up -d
docker compose logs --tail=200 homeassistant
El ID de imagen no guarda por sí solo una imagen recuperable fuera del VPS. Registra tag/digest inmutable, conserva acceso, lee notas y prueba integraciones. Si migró la base/configuración, vuelve con su copia correspondiente. No sigas latest automáticamente.
docker compose ps
docker compose logs --tail=200 homeassistant
sudo journalctl -u caddy -n 100 --no-pager
ss -lntp | grep -E ':8123|:80|:443'
Comprueba listener 8123, upstream, proxy de confianza, logs, permisos y memoria.
Comprueba límites de red, puente doméstico, cuenta cloud, rutas VPN y multicast. El puente local suele resultar más mantenible que reenviar broadcasts al VPS.
Revisa logs, actualización de entidades, zona horaria, triggers duplicados y mensajes retained MQTT. Sondear cada segundo no repara un dispositivo desconectado y puede sobrecargarlo.
- Dominio, HTTPS, MFA y proxy verificados.
- Límites Container/OS/Supervised comprendidos.
- MQTT autenticado y listeners administrativos privados.
- Cada dispositivo tiene ruta cloud/VPN/puente funcional.
- Configuración, Compose, servicios y claves con copia externa.
- Restauración separada y segura probada.
- Imagen, migración y reversión documentadas.
Diseña dispositivos y red antes de mover automatizaciones. El VPS complementa la red doméstica, sin reemplazar radios físicos ni descubrimiento local.