Installing Home Assistant on VPS: A Complete Guide with Docker and SSL
TL;DR
In this guide, we will step-by-step set up Home Assistant on a Virtual Private Server (VPS) using Docker for isolation and ease of management, and ensure secure access via HTTPS with an automatic SSL certificate from Let's Encrypt. You will learn how to prepare the server, deploy Home Assistant, configure access via a domain name, and secure it, gaining full control over your smart home system without relying on third-party cloud services.
- Full Control: Deploying Home Assistant on your own VPS for maximum privacy and flexibility.
- Using Docker: Ensuring easy installation, isolation, and updates for Home Assistant and its components.
- Secure Access: Configuring HTTPS with an automatic SSL certificate via Caddy for secure remote connection.
- Scalability: Choosing a VPS configuration sufficient for current needs and future smart home system expansion.
- Maintenance and Backups: Including backup and update strategies for long-term stability.
What We Configure and Why
Home Assistant is a powerful open-source platform for smart home automation that prioritizes privacy and local control. It allows you to combine devices from various manufacturers into a single system, create complex automations, monitor sensor states, and manage all aspects of your home from a unified interface.
In this guide, we will deploy Home Assistant on a Virtual Private Server (VPS). This solution offers several key advantages:
- Full Control and Privacy: Your data remains on your server. You are not dependent on cloud services and their privacy policies.
- Flexibility and Scalability: A VPS provides significantly more resources than single-board computers like Raspberry Pi, allowing you to handle more integrations, automations, and store a larger volume of data without performance degradation.
- 24/7 Reliability: VPS are typically hosted in professional data centers with high availability and stable internet connectivity, ensuring uninterrupted operation of your smart home system.
- Remote Access: We will configure secure access to Home Assistant from anywhere in the world via a domain name and HTTPS, protected by an SSL certificate.
As alternatives to Home Assistant on a VPS, you can consider:
- Home Assistant Green/Yellow or Raspberry Pi: A local solution, simple to deploy, but limited in resources and requiring constant power and internet connection in your home.
- Cloud Smart Home Platforms (Google Home, Amazon Alexa, Apple HomeKit): Convenient, but often require transferring your data to their servers and limit control over devices.
- Managed Solutions (e.g., Home Assistant Cloud): Offer convenient remote access and integration with voice assistants for a subscription fee, but still depend on a third-party service.
Choosing a self-hosted solution on a VPS allows combining the advantages of local control with the reliability and performance of cloud infrastructure, making it ideal for advanced users and those who value privacy.
What VPS Configuration is Needed for This Task
Choosing the right VPS configuration is critical for stable and fast Home Assistant operation, especially as your smart home system grows.
Minimum Requirements (for small installations, up to 20-30 devices/integrations)
- CPU: 2 cores (x86-64 architecture)
- RAM: 4 GB (Home Assistant can be memory-intensive, especially with a database and many add-ons)
- Disk: 80 GB SSD (a fast disk is important for the Home Assistant database and quick file access; 80 GB provides room for logs, backups, and database growth)
- Network: 100 Mbps (sufficient for remote access and updates)
- Operating System: Ubuntu Server 24.04 LTS (recommended)
Recommended VPS Plan (for medium to large installations, 50+ devices, cameras, voice assistants)
- CPU: 4 cores
- RAM: 8 GB
- Disk: 160 GB SSD (with room for long-term data, history, and potential Docker images of other services)
- Network: 1 Gbps (for fast downloads, video streaming from cameras)
- Operating System: Ubuntu Server 24.04 LTS
For renting a VPS with these characteristics, you can consider a VPS with the specified characteristics, suitable for reliable Home Assistant hosting.
When a Dedicated Server is Needed, Not a VPS
A dedicated server might be needed in rare cases if:
- You are planning a very large Home Assistant installation (hundreds of devices, dozens of IP cameras with video processing).
- You need absolutely all server resources without virtualization.
- You want to host many other resource-intensive applications on the server besides Home Assistant.
- Specific hardware is required that is not available on a VPS (e.g., GPU for AI tasks).
In most cases, a well-configured VPS is sufficient for Home Assistant. If your project requires maximum performance and full control over the hardware, you can consider a suitable dedicated server.
Location: What it Affects
The choice of VPS server location can affect several aspects:
- Latency: If you plan to use Home Assistant to control devices requiring minimal latency (e.g., for instant sensor response), it's better to choose a server geographically close to you or your home. However, for most automations and remote access, a latency of 50-150 ms will not be critical.
- Legislation: Depending on your preferences for privacy and data storage, you can choose a jurisdiction that meets your requirements.
- Price: VPS prices can vary depending on the data center location.
For Home Assistant working with devices in your home, the primary importance is a stable and sufficiently fast internet connection between your home and the VPS. Geographical proximity to your physical smart home devices is less critical, as most modern Home Assistant integrations use API calls rather than direct local access to devices, unless you are configuring specific local bridges.
Server Preparation
Before installing Home Assistant, you need to perform basic setup and secure your VPS. We will use Ubuntu Server 24.04 LTS as a stable and widely used operating system.
1. Connect via SSH
Connect to your new VPS using SSH. You will need the server's IP address and credentials (usually the root user and password, or an SSH key).
ssh root@YOUR_VPS_IP_ADDRESS
2. Create a New User and Configure Sudo
Working as the root user is unsafe. Let's create a new user and add them to the sudo group.
# Replace 'your_username' with the desired username
adduser your_username
usermod -aG sudo your_username
Now, exit the root session and log in as the new user:
exit
ssh your_username@YOUR_VPS_IP_ADDRESS
3. Configure SSH Key Authentication (Recommended)
If you are not yet using SSH keys, this is the most secure authentication method. Generate keys on your local machine if you don't have them:
# On your LOCAL machine
ssh-keygen -t ed25519 -C "[email protected]"
Copy the public key to the server:
# On your LOCAL machine
ssh-copy-id your_username@YOUR_VPS_IP_ADDRESS
After successful copying, disable password login for root and your new user. Edit the SSH server configuration file:
sudo nano /etc/ssh/sshd_config
Find and change the following lines (or add them if missing):
# Disable password login
PasswordAuthentication no
# Disable root login
PermitRootLogin no
Restart the SSH service:
sudo systemctl restart sshd
4. Update the System
Always start by updating the package database and installed packages.
sudo apt update && sudo apt upgrade -y
5. Configure Firewall (UFW)
UFW (Uncomplicated Firewall) is an easy-to-use interface for iptables. We will configure it to allow only the necessary ports.
# Install UFW if not already installed
sudo apt install ufw -y
# Allow SSH (port 22)
sudo ufw allow ssh
# Allow HTTP (port 80) and HTTPS (port 443) for web access and Let's Encrypt
sudo ufw allow http
sudo ufw allow https
# Allow Home Assistant port (usually 8123), if direct access without proxy is planned
# However, we will use Caddy as a reverse proxy, so this port can be left closed from outside
# sudo ufw allow 8123/tcp
# Enable the firewall
sudo ufw enable
Confirm that you want to proceed if UFW warns about a potential SSH connection disruption. Check the status:
sudo ufw status verbose
6. Install Fail2Ban
Fail2Ban scans logs and blocks IP addresses showing signs of malicious attacks (e.g., multiple failed SSH login attempts).
sudo apt install fail2ban -y
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
Create a local configuration file for Fail2Ban so that your changes are not overwritten during package updates:
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo nano /etc/fail2ban/jail.local
In the jail.local file, ensure that the [sshd] section is active (enabled = true) and, if desired, configure bantime (ban time) and maxretry (number of attempts).
# Example sshd section in jail.local
[sshd]
enabled = true
port = ssh
logpath = %(sshd_log)s
backend = %(sshd_backend)s
# bantime = 1d # Ban for 1 day
# maxretry = 3 # Ban after 3 failed attempts
Save changes and restart Fail2Ban:
sudo systemctl restart fail2ban
7. Install Basic Utilities
Let's install a few useful utilities that will come in handy during installation and maintenance.
sudo apt install curl wget git htop ntpdate -y
ntpdate will help synchronize system time, which is important for SSL certificates and many network services. In modern Ubuntu, systemd-timesyncd is usually already active and quite effective.
# Check time synchronization status
timedatectl status
Software Installation — Step-by-Step
Now that the server is prepared, let's proceed with installing Docker, Docker Compose, Home Assistant, and a reverse proxy with SSL.
1. Installing Docker Engine (relevant for 2026)
We will install Docker from the official Docker repository to get the latest versions.
# Update the package list
sudo apt update
# Install necessary packages to install Docker from the repository
sudo apt install ca-certificates curl gnupg lsb-release -y
# Add Docker's official GPG key
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
# Add the Docker repository to APT sources
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
# Update the package list with the new Docker repository
sudo apt update
# Install Docker Engine, Docker CLI, and containerd
sudo apt install docker-ce docker-ce-cli containerd.io -y
# Check Docker status
sudo systemctl status docker
Add our user to the docker group to execute Docker commands without sudo (SSH reconnection will be required).
# Replace 'your_username' with your username
sudo usermod -aG docker your_username
# Reconnect to SSH for changes to take effect
exit
ssh your_username@YOUR_VPS_IP_ADDRESS
Verify that Docker is working by running a test container:
docker run hello-world
2. Installing Docker Compose Plugin
In modern Docker versions, Docker Compose is a Docker CLI plugin. Let's install it:
sudo apt install docker-compose-plugin -y
# Check Docker Compose version
docker compose version
3. Preparing the Directory Structure for Home Assistant
Let's create a directory where Home Assistant configuration files and docker-compose.yml will be stored.
mkdir ~/homeassistant
cd ~/homeassistant
4. Creating the docker-compose.yml file for Home Assistant
Create the file docker-compose.yml. In it, we will define the Home Assistant service, its ports, volumes for data storage, and the restart policy.
nano docker-compose.yml
Insert the following content:
# Docker Compose file version
version: '3'
# Define services
services:
homeassistant:
# Use the official Home Assistant Core image
# The relevant image for 2026 will be 'homeassistant/home-assistant:stable' or 'homeassistant/home-assistant:2026.x.x'
image: homeassistant/home-assistant:stable
# Container name
container_name: homeassistant
# Specify which container ports to map to the host
# Port 8123 - standard Home Assistant port
# We map it to local port 8123, which will only be accessible within the VPS
# External access will be via Caddy (reverse proxy)
ports:
- "127.0.0.1:8123:8123"
# Volumes for Home Assistant data storage
# /path/to/your/config:/config - replace with the actual path on your VPS
volumes:
- ./config:/config
- /etc/localtime:/etc/localtime:ro
# Allow the container access to the host network for device discovery
# network_mode: host # Can be used, but then port 8123 will be open on all VPS interfaces
# It's better to use a bridge network and configure trusted_proxies in HA
# Automatically restart the container if it stops
restart: unless-stopped
# Set timezone
environment:
TZ: Europe/Moscow # Or your timezone
Save the file (Ctrl+O, Enter, Ctrl+X).
5. Starting Home Assistant
Start the Home Assistant container using Docker Compose:
docker compose up -d
Check the container status:
docker compose ps
docker logs homeassistant
The first launch of Home Assistant may take several minutes while it loads all necessary components.
6. Installing and Configuring Caddy (Reverse Proxy with Auto-SSL)
Caddy is a powerful web server that automatically manages SSL certificates from Let's Encrypt. It is ideal for our use case.
6.1. Adding the Caddy Repository
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. Installing Caddy
sudo apt install caddy -y
6.3. Configuring Caddyfile
Create or edit the Caddy configuration file. Ensure you have a domain name (e.g., ha.yourdomain.com) pointing to your VPS's IP address.
sudo nano /etc/caddy/Caddyfile
Remove all existing content and insert the following, replacing ha.yourdomain.com with your actual domain:
# Your domain for Home Assistant
ha.yourdomain.com {
# Enable automatic issuance and renewal of Let's Encrypt SSL certificate
tls [email protected]
# Reverse proxy to Home Assistant, running on local port 8123
reverse_proxy 127.0.0.1:8123 {
# Headers required for correct WebSocket operation and remote 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}
}
# Enable compression if needed (optional)
# encode gzip zstd
# Logging (optional)
# log {
# output file /var/log/caddy/ha_access.log
# }
}
Save the file (Ctrl+O, Enter, Ctrl+X).
6.4. Checking and Starting Caddy
# Check Caddyfile syntax
sudo caddy validate --config /etc/caddy/Caddyfile
# Restart the Caddy service to apply changes
sudo systemctl reload caddy
# Check Caddy status
sudo systemctl status caddy
Ensure Caddy has successfully started and obtained an SSL certificate. This may take a few seconds.