Installation and operation of HS4 using Docker
Overview
Docker provides a simple way to install and run HS4 on almost any Linux distribution without manually installing dependencies. The HomeSeer Docker image contains everything required to run HS4 while keeping your installation isolated from the host operating system.
Note
This guide assumes you already have Docker installed on your Linux system.
Step 1 – Download the Docker Compose configuration file
Download docker-compose.yml from the GitHub project
wget https://raw.githubusercontent.com/HomeSeer/homeseer-docker/main/docker-compose.yml
Step 2 – Configure Your Installation
Review the docker-compose.yml file.
The most important settings are:
Image Tag
The latest tag tracks the docker image for the latest HS4 release version
image: ghcr.io/homeseer/homeseer:latest
The beta tag tracks the docker image for the latest HS4 beta version
image: ghcr.io/homeseer/homeseer:beta
Alternatively, you can use a specific version number as the tag
image: ghcr.io/homeseer/homeseer:4.2.23.0
Mapped Volume Path
HomeSeer stores all its application files (binaries, configuration, plugins, events, devices, and settings) inside a mapped /homeseer folder on the host.
This allows your HomeSeer configuration to survive container updates or recreation.
Example:
volumes:
- /usr/local/homeseer:/homeseer
which means the files will be written to /usr/local/homeseer. If you change this path, do not forget to change the DOCKER_HOMESEER_HOST_ROOT environment variable as well.
Do not delete this folder unless you intend to completely reset your HomeSeer installation.
Network Ports
By default HomeSeer exposes several ports.
Common ports include:
|
Port |
Purpose |
|---|---|
|
80 |
HomeSeer Web Interface |
|
10200 |
HSTouch |
|
10300 |
myHS |
|
10401 |
Speaker Client |
|
11000 |
ASCII/JSON API |
If a plugin needs to expose an additional port, add a mapping to the ports section
Step 3 – Start HomeSeer
Start the container using Docker Compose:
sudo docker compose up -d
Docker will:
-
Download the HomeSeer image (if necessary)
-
Create the container
-
Start HomeSeer automatically
On the first run of the homeseer container, the script will take a few minutes while it installs the HomeSeer application files to the /homeseer mapped volume path. Subsequent container restarts will occur much faster as the HomeSeer application files are already installed. If the container is removed and a new container is launched, the HomeSeer application files will be re-installed even if they already exist in the /homeseer mapped volume path.
Step 4 – Access HomeSeer
Once the container is running, open a web browser and navigate to your Linux host IP address:
http://<Linux-IP-Address>
Example:
http://192.168.1.50
The HomeSeer setup wizard will appear if this is a new installation.
Managing the Container
Stop HomeSeer
sudo docker compose stop
If "No Password Required for Local (same subnet) Login" is disabled in the HS4 network settings, you must provide valid credentials in docker-compose.yml in order for HS4 to shutdown gracefully:
HOMESEER_CREDENTIALS: "username:password"
Start HomeSeer
sudo docker compose up -d
View Logs
If HomeSeer is not starting correctly, view the container logs:
docker compose logs -f
This displays the HomeSeer startup process and any error messages.
Updating HomeSeer
When a newer Docker image becomes available:
-
Stop the container.
sudo docker compose stop
-
Download the latest image.
sudo docker compose pull
-
Start the updated container.
sudo docker compose up -d
Because your HomeSeer application files are stored in a persistent directory, your configuration and plugins remain intact after the update. However, it is always a good idea to make sure you have a complete backup of the /homeseer mapped volume path prior to any upgrades
Additional Resources