VPS Tutorials
Home Assistant Container on a VPS: MQTT, HTTPS and LAN limits
Deploy Home Assistant Container with Docker and Caddy. Plan home-to-VPS connectivity, correct MQTT listeners and proxy trust, secure accounts, control recorder growth and test consistent backups before upgrades.

Home Assistant can coordinate lights, sensors, cameras, energy monitoring and automation. A VPS is useful for cloud integrations and deliberately connected remote devices, but it cannot automatically see your home's LAN. Keep essential home control usable when the internet or VPS is unavailable.
This guide uses Ubuntu 24.04, Docker Compose and Home Assistant Container.
- Container runs without Supervisor or the Home Assistant OS app/add-on store; run supporting services separately.
- Home Assistant OS includes the managed environment and suits a supported home machine or compatible VM, rather than nesting its installation inside an ordinary Docker container.
- Supervised is a legacy installation approach with strict host assumptions; use a currently supported method for a new deployment.
USB Zigbee/Z-Wave adapters and local Bluetooth usually belong on a home host. Cloud API and routed MQTT integrations can suit a VPS. Matter is not automatically cloud-friendly: local IPv6, multicast, a controller and sometimes Thread border-router connectivity still matter.
| Resource | Light lab | Planning for sustained use |
|---|---|---|
| CPU | 2 vCPU | 2-4 vCPU |
| RAM | 2 GB | 4 GB or more |
| Disk | 30 GB SSD | 60 GB SSD or more |
| Host | Ubuntu 22.04/24.04 | Ubuntu 24.04 LTS |
| Domain | ha.example.com | Dedicated automation subdomain |
History, entities and camera data change these budgets. Check free -h, df -h and docker stats; see VPS sizing.
- Choose each device's path: cloud API, authenticated MQTT, or an explicitly supported local bridge.
- Use verified HTTPS or a private WireGuard/Tailscale path for administration.
- Keep MQTT 1883 private; expose a secured listener only when required.
- Keep camera streams on the home LAN or a suitable VPN rather than routing all video through a small public VPS.
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
Review the root-level convenience installer or use supported packages. Docker membership grants powerful host access. Persist /config outside the container and avoid simultaneous manual edits to configuration.yaml.
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
The example's Asia/Shanghai time zone is a placeholder for that location; choose your actual IANA zone and set the home's location/time zone during onboarding. Pin an exact supported image release for controlled upgrades instead of silently following stable.
Host networking helps discover devices on the VPS's connected network; it does not forward the home LAN's mDNS/SSDP broadcasts. It can also expose 8123 on host interfaces, so restrict that listener/firewall. Without discovery needs, use a bridge with publication 127.0.0.1:8123:8123 instead. Check whether the selected image includes the healthcheck's curl command; an invalid probe is not proof of application failure.
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
Open http://127.0.0.1:8123 through the workstation tunnel and create the administrator, home location and time zone.
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
With a host-side Caddy and host-network application, this proxy example is appropriate:
http:
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1
Merge it into the existing http section, then validate/restart the application. With bridge networking, trust the actual proxy address seen by the container instead of assuming 127.0.0.1. Never trust 0.0.0.0/0. Let one gateway own 80/443 and use HSTS/includeSubDomains only where HTTPS works. See Caddy troubleshooting.
This service belongs under the same Compose services mapping, with persistent directories prepared first:
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
The older broker configuration below needs a correction for a bridge-network container: binding inside the container to its own loopback prevents Docker's forwarded connection from reaching it.
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/
Use listener 1883 inside the broker; keep the host publication bound to 127.0.0.1 or the intended private interface. Keep allow_anonymous false, create the password file with mosquitto_passwd, and create an ACL granting each device only its intended topics. Use -c only for a new password file, because it overwrites an existing one. Grant the Home Assistant account needed state/command/discovery topics, without sharing its credential with every device. Ensure the selected image's user can read config and write data/log paths.
- A host-network Home Assistant connects to 127.0.0.1:1883; Docker service-name DNS is for containers sharing a bridge network.
- Home devices cannot connect to the VPS's loopback. Use a VPN address/private listener, or an SSH forwarding design appropriate to the device.
- Use TLS for MQTT across untrusted networks; authentication alone does not encrypt traffic.
- Diagnose DNS, VPN routing, TCP reachability, user ACL and topic names in order; do not switch to anonymous access.
- Use supported cloud integrations over outbound HTTPS where available.
- Keep MQTT/Zigbee2MQTT or a supported bridge on the home side and connect deliberately to the VPS.
- Use WireGuard/Tailscale for IP routing between sites.
- If discovery requires multicast forwarding, configure it explicitly and narrowly; an ordinary subnet route does not carry mDNS/SSDP automatically.
These are choices, not a universal reliability ranking. A home host remains the practical option for USB radios, Bluetooth and strongly local camera/Matter integrations.
Start with one sensor and one light:
- Check state-update timing.
- Verify triggers and the intended time zone.
- Test disconnect and reconnect behavior.
- Look for authentication failures or reconnect loops.
- Measure history growth.
SQLite is the default recorder database. Reduce unnecessary entities/retention first; use an external database only if supported by the installed release and justified by measurements. Back it up separately. Store camera recordings in an NVR or appropriate dedicated storage, not inside /config.
- Enable administrator MFA and give ordinary users only supported permissions; dashboard visibility is not entity-level isolation.
- Close unnecessary public ports, especially 8123 and MQTT; expose 80/443 only if needed.
- Disable anonymous MQTT and use separate device accounts.
- Keep long-lived cloud keys out of exposed automation code.
- Restrict the dashboard to VPN users when that is your design; a public Caddy still needs access restrictions.
- Review login failures and unexpected addresses.
- Review custom integrations and their access before installation.
- Keep home addresses, camera URLs and tokens out of public repositories.
Test WebSocket/long-lived connections and bypass inappropriate CDN caching. Do not let one household's authenticated response be cached for another user.
Configuration includes automations, credentials, users, integrations and often SQLite history. This archive command is suitable only after obtaining a consistent database/configuration state:
mkdir -p /opt/homeassistant/backups
tar -czf /opt/homeassistant/backups/homeassistant-$(date +%F).tgz -C /opt/homeassistant config
The stopped-container sequence is safer for a file-level copy:
docker compose stop
tar -czf /opt/homeassistant/backups/homeassistant-safe-$(date +%F).tgz -C /opt/homeassistant config
docker compose start
Also save Compose, external MQTT config/credentials/data and any external recorder database. Protect and encrypt offsite copies; preserve any backup encryption recovery key. Restore the same exact release on a clean host and verify login, integrations, automations, MQTT and history. Prevent a test restore from operating real devices unexpectedly. See restore drills.
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
An image ID alone is not an offsite rollback image. Record an immutable tag/digest, retain access to it, check release notes and test integrations before maintenance. Restore matching configuration/database if a migration prevents simple image rollback; do not follow latest blindly.
docker compose ps
docker compose logs --tail=200 homeassistant
sudo journalctl -u caddy -n 100 --no-pager
ss -lntp | grep -E ':8123|:80|:443'
Check actual 8123 binding, Caddy upstream, proxy trust, application logs, directory ownership and memory.
Verify the network boundary before blaming an integration. Check home bridge, cloud account, VPN routes and multicast requirements. A local bridge is often easier to maintain than forwarding home broadcasts to a public VPS.
Check logs, entity update times, time zone, duplicate triggers and retained MQTT messages. One-second polling does not repair an offline device and can overload its API.
- Domain, HTTPS, MFA and proxy trust are verified.
- Container/OS/legacy Supervised boundaries are understood.
- MQTT is authenticated; management listeners remain private.
- Each device has a working cloud, VPN or bridge path.
- Config, Compose, service data and keys have offsite backups.
- A safe separate restore has been tested.
- Image, migration and rollback policy is recorded.
Choose the device/network layout before moving automation to a VPS. Remote hosting complements a home network; it does not replace its physical radios or local discovery.