Run Home Assistant in Docker on a VPS

Updated 6 November 2026 · Standard formula, shown below

This guide walks you through installing Home Assistant (the full Home Assistant Core, not the supervised version) inside a Docker container on a VPS. You’ll end up with a remotely accessible smart-home hub that runs 24/7, with automatic restarts, isolated from the host OS. Before starting, you need a VPS with at least 2 GB of RAM, a public IP, and SSH access. You’ll also need a basic comfort with the Linux command line.

What You’ll Need

A VPS running Ubuntu 22.04 or Debian 12 (other distros work, but these are easiest)
At least 2 GB RAM and 20 GB disk space
Root or sudo access via SSH
A domain name (optional but recommended for HTTPS)
Ports 80 and 443 open in your VPS firewall

Step-by-Step

Connect to your VPS via SSH: ssh user@your_server_ip. Update the package list and upgrade existing packages: sudo apt update && sudo apt upgrade -y.
Install Docker and Docker Compose (if not already installed). The easiest way is using the official convenience script: curl -fsSL https://get.docker.com -o get-docker.sh, then sudo sh get-docker.sh. Verify with docker --version.
Create a directory for Home Assistant: mkdir -p ~/homeassistant and navigate into it: cd ~/homeassistant.

Create a docker-compose.yml file using your favorite text editor (e.g., nano docker-compose.yml). Paste the following content:

version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    volumes:
      - ./config:/config
    environment:
      - TZ=America/New_York   # Replace with your timezone
    ports:
      - "8123:8123"
    privileged: true

Replace the timezone with your own (find yours at timedatectl or this list). If you don’t need hardware access, you can remove privileged: true for better security.

Start the container: sudo docker compose up -d. This downloads the image and starts Home Assistant. Wait a couple of minutes for it to initialize.
Verify it’s running: sudo docker ps should show a container named homeassistant with status Up. Check the logs with sudo docker logs homeassistant to see startup progress.
Access the web interface: Open http://your_server_ip:8123 in your browser. You’ll see the onboarding wizard â€“ create your user account and name your home.
Set up a reverse proxy (optional but recommended) to access Home Assistant securely via a domain with HTTPS. Install Nginx: sudo apt install nginx. Create a config file at /etc/nginx/sites-available/homeassistant with:
```
server {
    listen 80;
    server_name your_domain.com;
    location / {
        proxy_pass http://127.0.0.1:8123;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
    
```
Enable it with sudo ln -s /etc/nginx/sites-available/homeassistant /etc/nginx/sites-enabled/, test with sudo nginx -t, then reload: sudo systemctl reload nginx. For HTTPS, use Certbot: sudo apt install certbot python3-certbot-nginx and sudo certbot --nginx -d your_domain.com.
Configure automatic updates (optional): Add a cron job to pull and restart the container weekly: sudo crontab -e and add 0 4 * * 0 cd ~/homeassistant && sudo docker compose pull && sudo docker compose up -d.

Common Mistakes

Forgetting to set the timezone â€“ Home Assistant will default to UTC, causing automations to fire at wrong times.
Using privileged: true unnecessarily â€“ It’s needed for some USB devices or if you plan to use Docker inside HA, but it reduces security. Only enable if you really need it.
Blocking port 8123 â€“ If you can’t access the web UI, check your firewall (ufw) and cloud provider security groups.
Not using a volume for config â€“ If you don’t mount ./config, all your settings are lost when the container is recreated.
Running as root â€“ Always use sudo for Docker commands, but don’t run the container as root inside if you can avoid it.

Tips

Back up your ~/homeassistant/config directory regularly â€“ it contains all your automations, configurations, and the database.
Use a named volume instead of a bind mount if you prefer Docker-managed storage: volumes: - homeassistant-config:/config and add volumes: homeassistant-config: at the bottom.
If you plan to use Zigbee or Z-Wave USB sticks, pass them through with devices: - /dev/ttyUSB0:/dev/ttyUSB0 instead of privileged: true.
Set up a swap file if your VPS has low memory: sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile.
Monitor resource usage with docker stats to ensure your VPS isn’t overloaded.

Troubleshooting

Container won’t start â€“ Run sudo docker logs homeassistant to see errors. Common issues: port already in use (change the port mapping), or bad permissions on the config directory (sudo chown -R 1000:1000 ./config).
Web UI unreachable â€“ Check that the container is running (docker ps), the port is open (sudo ufw status), and you’re using the correct IP. Try accessing from your local browser with curl http://localhost:8123 on the VPS.
Home Assistant says â€œUnable to load the dashboardâ€� â€“ Usually a corrupted database. Stop the container, rename config/home-assistant.db to .bak, and start again. You’ll lose history but keep your config.
After an update, automations break â€“ Check the logs for deprecation warnings. You can pin to a specific version by changing stable to e.g. 2023.5.3 in the image tag.
Reverse proxy returns 502 Bad Gateway â€“ Verify Nginx is running, and that the proxy_pass points to the correct port. Also ensure Home Assistant is listening on all interfaces (it does by default).

Frequently Asked Questions

Can I use this method to add Home Assistant to an existing Docker setup?

Yes, just add the service to your existing docker-compose.yml and run docker compose up -d. Ensure no port conflicts.

How do I update Home Assistant?

Navigate to ~/homeassistant and run sudo docker compose pull then sudo docker compose up -d. The container will be recreated with the new image. Your config persists.

Can I use this to control devices on my local network?

Yes, but you’ll need to configure the VPS to reach those devices. If they’re on a different network, you may need a VPN or port forwarding. For local-only devices, consider running Home Assistant on a Raspberry Pi instead.

Is it safe to expose Home Assistant to the internet?

It’s risky if you only use HTTP. Always use HTTPS via a reverse proxy. Also enable two-factor authentication in Home Assistant and avoid using default passwords.

What if I want to use add-ons like Node-RED or ESPHome?

Add-ons are only available in Home Assistant Supervised or OS installs. In Docker, you run those as separate containers and connect them to Home Assistant via the API or MQTT.

How much does it cost to run Home Assistant on a VPS?

It depends on the provider, but a small VPS with 2GB RAM costs around $5â€“10 per month. You can also use a free tier from some providers, but they may have limited resources.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.