Skip to main content
Your best option to get started with Homescript is to use the Homescript Docker image. This image comes pre-configured with everything you need to run Homescript, making it easy to deploy on any system that supports Docker.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

​
Steps to Run Homescript

  1. Pull the Homescript Docker Image: Open your terminal and run the following command to pull the latest Homescript image: 
    docker pull ghcr.io/homescript/server:stable
  2. Create a Configuration Directory: Create a directory on your host machine to store Homescript configuration files: 
    mkdir -p ~/homescript/config
cd ~/homescript
  3. Run Homescript in discovery mode: To start Homescript in discovery mode, run the following command: 
    docker run -it \
  --name homescript-discovery \
  -v ~/homescript/config:/app/config \
  ghcr.io/homescript/server:stable \
  discovery --mqtt-broker tcp://mosquitto:1883 --config config
    This will allow Homescript to scan for devices and generate initial configuration scripts. On completion, you have to have a look at the generated configuration files in the ~/homescript/config directory and make any necessary adjustments. There’s should be a bunch of example scripts to get you started.
  4. Create a Docker Compose File: Create a docker-compose.yml file in the configuration directory with the following content: 
    services:
  homescript:
    image: ghcr.io/homescript/server:stable
    container_name: homescript
    volumes:
      - ./config:/app/config
    restart: unless-stopped
    depends_on:
      - mosquitto
  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    volumes:
      - ./zigbee2mqtt-data:/app/data
    devices:
      # Adjust based on your Zigbee adapter
      - /dev/ttyUSB0:/dev/ttyUSB0
    restart: unless-stopped
    ports:
      # Frontend port
      - 8080:8080
    depends_on:
      - mosquitto
  mosquitto:
    image: eclipse-mosquitto
    container_name: mosquitto
    volumes:
      - ./mosquitto-data:/mosquitto/data
      - ./mosquitto-config:/mosquitto/config
    ports:
      - "1883:1883"
    restart: unless-stopped
  5. Start Homescript: Navigate to the configuration directory and start the Homescript container using Docker Compose: 
    cd ~/homescript
docker-compose up -d
  6. Re-configure Homescript: Just edit the configuration files in the ~/homescript/config directory to customize your setup. If you installed more devices after the initial discovery, you can run Homescript in discovery mode again to update your configuration.