Deploy Home Assistant with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it straightforward to get Home Assistant accessible remotely.

This guide covers deploying Home Assistant Core on a VPS for remote access and cloud automations. Note that deploying on a VPS is ideal for remote dashboards and API-based integrations, but local device access (Zigbee, Z-Wave, Bluetooth) requires running Home Assistant on your local network.

Prerequisites

• A VPS with at least 2 vCPUs, 2 GB RAM, and 10 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., ha.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  home-assistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    ports:
      - "8123:8123"
    environment:
      - TZ=${TZ:-UTC}
    volumes:
      - ../files/home-assistant-config:/config
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8123/ || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Note: For VPS deployments, standard port mapping works well. If you were running this on a local server with IoT devices, you would use network_mode: host and privileged: true for direct device access — but that is not needed for remote/cloud deployments.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
TZ	Server timezone (tz database format)	America/New_York

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. Home Assistant uses the timezone for automations, sunrise/sunset calculations, and log timestamps.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/home-assistant-config — All Home Assistant configuration files, automations, scripts, custom integrations, and the internal SQLite database

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/homeassistant) because Dokploy may clean them during redeployment.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., ha.yourdomain.com)
3. Set the container port to 8123
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your Home Assistant container. You may need to add use_x_forwarded_for: true and trusted_proxies to your Home Assistant configuration.yaml for proper IP detection behind the reverse proxy.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see the home-assistant container pull and start
3. Check the Logs tab for the home-assistant service. Look for: Home Assistant initialized followed by Starting Home Assistant
4. Open https://ha.yourdomain.com in your browser — you should see the Home Assistant onboarding wizard
5. Create your admin account and configure your home location, timezone, and unit system

Troubleshooting

Home Assistant shows "400 Bad Request" behind reverse proxy Add the following to your configuration.yaml (in the ../files/home-assistant-config volume) to trust Dokploy's Traefik proxy:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.16.0.0/12
    - 192.168.0.0/16
    - 10.0.0.0/8

Integrations requiring local network access don't work VPS deployments cannot access local IoT devices (Zigbee sticks, Z-Wave controllers, Bluetooth). For those integrations, run Home Assistant on your local network. A VPS deployment is best suited for cloud-based integrations (weather APIs, MQTT brokers, webhooks).

Database errors or slow performance Home Assistant uses SQLite by default. For large installations with many entities and history, consider adding a MariaDB or PostgreSQL service to the compose file and configuring the recorder component to use it.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Home Assistant in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Home Assistant.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.