Install ESPHome with Docker on a VPS

This guide walks you through installing ESPHome using Docker on a Virtual Private Server (VPS). By the end, you’ll have a web-based dashboard where you can create, edit, and flash firmware to your ESP32 or ESP8266 devices remotely. You’ll need a VPS with a public IP, SSH access, and Docker installed.

What You’ll Need

• A VPS running Linux (Ubuntu/Debian recommended) with at least 1 GB RAM and 20 GB disk.
• SSH access to the VPS (root or a user with sudo privileges).
• Docker and Docker Compose installed. If not present, the guide includes installation steps.
• A domain name (optional but recommended for HTTPS) pointing to your VPS’s IP.
• Ports 6052 (ESPHome dashboard) and 8266 (OTA upload) open in your firewall.

Step-by-Step

1. Connect to your VPS via SSH. Use your terminal: ssh user@your-server-ip. Update the system packages: sudo apt update && sudo apt upgrade -y.
2. Install Docker and Docker Compose. If Docker isn’t already installed, run: curl -fsSL https://get.docker.com | sh. Then install Compose plugin: sudo apt install docker-compose-plugin. Verify with docker --version and docker compose version.
3. Create a directory for ESPHome. mkdir ~/esphome && cd ~/esphome. This will hold your configuration files and the Docker Compose setup.
4. Create a docker-compose.yml file. Using a text editor (e.g., nano docker-compose.yml), paste the following:

   version: '3'
   services:
     esphome:
       image: ghcr.io/esphome/esphome:latest
       container_name: esphome
       volumes:
         - ./config:/config
         - /etc/localtime:/etc/localtime:ro
       environment:
         - ESPHOME_DASHBOARD_USE_PING=true
       ports:
         - "6052:6052"
         - "8266:8266"
       restart: unless-stopped

   Save and exit.

5. Start the container. Run sudo docker compose up -d. This pulls the ESPHome image and starts the dashboard. Check status: sudo docker compose ps.
6. Access the dashboard. Open your browser and go to http://your-server-ip:6052. You should see the ESPHome web interface.
7. Add a device. Click the + New Device button, give it a name (e.g., livingroom-sensor), select your board (ESP32 or ESP8266), and click Install. Choose Plug into this computer to download the firmware binary.
8. Flash the firmware. Connect your ESP device via USB to your local computer, use a tool like ESPHome Flasher or esptool to upload the downloaded binary. Alternatively, you can use the dashboard’s Install option with a USB-connected device if you have the ESPHome CLI installed locally.
9. Configure OTA updates. In the dashboard, edit your device’s YAML configuration. Add an ota: section with a password (or leave blank for no password). Then, when you make changes, click Install and choose Wirelessly to push updates over Wi-Fi without re-flashing via USB.
10. Secure the dashboard (optional but recommended). Since the dashboard is open on port 6052, anyone can access it. Use a reverse proxy like Nginx or Caddy with HTTPS, or add basic authentication via ESPHome’s built-in web_server component with a password.

Common Mistakes

• Forgetting to open firewall ports. If the dashboard isn’t reachable, check your VPS firewall (ufw or cloud provider security groups). Allow ports 6052 and 8266.
• Using the wrong board type. Selecting ESP32 when you have an ESP8266 (or vice versa) causes compilation errors. Double-check your hardware.
• Not mounting the config directory. If you skip the volume mount, your configurations are lost when the container restarts. Always use ./config:/config.
• Ignoring OTA port. For wireless updates, the device connects to your VPS on port 8266. Ensure this port is open and the device can reach it.
• Running as root without sudo. Docker commands often need sudo. If you get permission errors, either add your user to the docker group (sudo usermod -aG docker $USER) or use sudo.

Tips

• Use a domain name. Set up a subdomain like esphome.example.com and use a reverse proxy with Let’s Encrypt for HTTPS. This avoids browser warnings and protects your dashboard.
• Back up your config. Regularly copy the ~/esphome/config directory to a safe location. You can also use a Git repository.
• Keep ESPHome updated. Run sudo docker compose pull and sudo docker compose up -d periodically to get the latest features and bug fixes.
• Use the dashboard’s logs. When a device fails to compile, click on the device name to view logs. They provide detailed error messages that help debug.
• Test locally first. If you’re new to ESPHome, set up a local installation on your PC to experiment. Then move to the VPS for remote management.

Troubleshooting

• Dashboard not loading. Check the container is running: sudo docker ps. If it’s not, view logs: sudo docker logs esphome. Common issues: port conflict (change the host port) or firewall blocking.
• Device not connecting to Wi-Fi. Verify your YAML has correct wifi: credentials. Check the device’s serial output during boot (via USB) for error messages like “Wi-Fi connection failed”.
• Compilation errors. The dashboard shows the error. Common causes: wrong board, missing component, or syntax error. Search the error message online; the ESPHome docs and community forums are helpful.
• OTA update fails. Ensure the device is on the same network as the VPS (or can reach it). Check that port 8266 is open. Try re-flashing via USB to reset the Wi-Fi configuration.
• Container restarts unexpectedly. Check logs for crashes. Ensure you have enough memory; if not, add swap space or upgrade your VPS.
• Permission denied when running docker. Add your user to the docker group: sudo usermod -aG docker $USER then log out and back in.

Frequently Asked Questions

Do I need a VPS to use ESPHome?

No. You can install ESPHome locally on a PC or Raspberry Pi. A VPS is useful for remote access and 24/7 operation, but not required.

Can I use ESPHome with any ESP32/ESP8266 board?

Yes, ESPHome supports most ESP32 and ESP8266 boards. You just need to select the correct board type in the device configuration.

How do I update the firmware on an already-flashed device?

If the device has OTA enabled, you can use the dashboard’s “Install” -> “Wirelessly” option. Otherwise, you’ll need to reconnect via USB and flash again.

Is the ESPHome dashboard secure by default?

No, it’s open on port 6052 without authentication. You should use a reverse proxy with HTTPS or add basic auth via the web_server component.

Can I run ESPHome on a free tier VPS?

Yes, many free tiers (like Oracle Cloud or Google Cloud) provide enough resources. Just ensure you have at least 512 MB RAM and a public IP.

What is the difference between the dashboard and the CLI?

The dashboard is a web UI for managing devices and configurations. The CLI (esphome command) is used for advanced tasks like compiling and flashing from a terminal.

Related

• Power Tool Gifts: What Not to Buy
• Brushless Power Tools: When Worth It?
• Niche Milwaukee Power Tools: What They’re Used For