Skip to content

docker

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docker

README.md

Docker Compose Setup with Home-Assistant Demo Server

The pre-defined docker-compose.yml is an all-in-one simulation setup including:

Important restrictions when used for developing custom integrations:

  • The Simulator runs in a bridged Docker network. Therefore, mDNS discovery won't work for detecting drivers on the host!
    See networking below for more information.
  • There is no suspend mode as with a real remote device.
    Depending on integration driver, suspend events must be handled and special actions be taken when the remote connects again.
  • Custom integrations cannot be run in the Simulator.
    • Custom integration archives can be uploaded. They will be extracted, validated, and an integration driver registered.
    • The installation is performed in the volatile temp folder and is removed after the container is stopped.
    • The registered custom integration driver must be deleted manually in the web-configurator or with a Core-API call.
  • Bluetooth is not available.
    • BT-remote entities cannot be created in the web-configurator.
  • Microphone access for voice assistants is not available.
    • We plan to add this feature later with an external application running on the Linux or Mac host (eventually also Windows).

UC Remote Device Model

The Simulator acts as a Remote 3 device by default. To switch to Remote Two, the following environment variable needs to be commented out in the core-simulator service, or changed to UC_MODEL=UCR2:

UC_MODEL=UCR3

User Accounts

See README in parent directory for the remote-core Simulator API accounts.

Home-Assistant:

A long lived access token is required for the integration-hass and speech-to-phrase services. A pre-generated access token is stored in the .env file that is used in the Docker compose files.

Docker Compose Commands

The default docker-compose file uses versioned images for the Core Simulator and the Home Assistant integration. To use the latest images, uses docker-compose-latest configuration by adding the -f docker-compose-latest.yml argument.

Check https://hub.docker.com/u/unfoldedcircle for new releases.
ℹ️ Official documentation on Docker Hub will be provided later.

⚠️ if you are using Linux or macOS, please make sure the subdirectories ui-env and upload are world-writeable.
If you get permission errors: chmod 777 ui-env upload.

⚠️ macOS requires Rosetta 2 when running on an M1 or newer platform. MacOS 26 or newer Docker Desktop versions might also require the --platform linux/amd64 argument to pull the amd64 based unfoldedcircle/core-simulator image.

Start in foreground:

docker-compose up

Start in background:

docker-compose up -d

Update to latest version:

docker-compose pull

Remove all containers but keep persisted remote-simulator data in data volume:

docker-compose down

Delete everything, including remote-simulator data:

docker-compose rm -v

See Docker Compose documentation for more information.

Optional Python integration library example

The docker-compose.yml file contains a commented out service named python-example which starts the Python integration library setup_flow example. This example is meant as a template for custom development or quickly trying out a Python based integration.

The Docker image will automatically be built when starting the services. It can also be built manually with docker-compose build.

  1. Uncomment the python-example service
  2. Start as usual: docker-compose up
  3. Register the driver manually, if auto-discovery doesn't work:
curl 'http://localhost:8080/api/intg/drivers' \
  --header 'Content-Type: application/json' \
  -u "web-configurator:1234" \
  --data '{
    "driver_id": "python_flow",
    "name": {
        "en": "Python flow"
    },
    "driver_type": "EXTERNAL",
    "driver_url": "ws://python-example:9081",
    "version": "0.1",
    "icon": "uc:cool",
    "enabled": true,
    "device_discovery": false,
    "setup_data_schema": {
    "title": {
      "en": "Example settings",
      "de": "Beispiel Konfiguration",
      "fr": "Exemple de configuration"
    },
    "settings": [
      {
        "id": "expert",
        "label": {
          "en": "Configure enhanced options",
          "de": "Erweiterte Optionen konfigurieren",
          "fr": "Configurer les options avancées"
        },
        "field": {
          "checkbox": {
            "value": false
          }
        }
      }
    ]
    }
  }'

Configuration

The remote-core Simulator runs with pre-configured defaults. Changing the configuration can have undesired effects, and we cannot support custom configurations.

Networking

This docker-compose setup has been configured with a bridged network, to easily connect to the provided Home Assistant integration and demo server. It requires a minimal set of mapped host ports and will work in every environment, even if the mapped ports are changed, if for example port 8080 is already used by another service on your machine.

The downside is, that mDNS discovery for custom integrations won't work (unless they also run in a container and are added to the docker-compose setup).

There are two solutions (plus a further one on Linux):

  1. Not using mDNS with the setup as-is: the integration driver needs to be registered manually with the REST Core-API.
  2. Run the core-simulator service with host networking and reconfigure the existing Home Assistant driver url.
  3. Only on Linux & unsupported: use an mDNS proxy or repeater, as for example raetha/mdns_repeater-docker.

Manual driver registration

Requirements to connect from a Docker container with bridge networking to a service running on your host:

  • Accessible IP of your host. This is important!
    • This is usually the IP address of your network adapter connecting to your network.
    • It should be in the same subnet as your router.
    • Any other "private" or virtual address, e.g. from Docker or virtualization software most likely won't work.
  • Host IP / port may not be blocked by a firewall.
  • Integration driver must bind to this network interface. Make sure it doesn't just listen on 127.0.0.1 or localhost.
    Some frameworks bind to localhost only if not configured otherwise!

To test if the integration driver is accessible it's best to perform a connection test from another machine, to make sure it's working. Either with a WebSocket client, or with a simple curl call:

curl $HOST_IP:9988
  • Port 9988 is the default port of the Node.js integration library. Adapt to your driver.
  • If the call returns Upgrade Required then you are good to go.

See driver registration in the core-api repository for a registration example with curl.

Web Server

⚠️ The remote-core Simulator uses a very simple built-in webserver to serve the static pages and the web-configurator.
The real remote device runs a dedicated webserver as reverse-proxy for the APIs and performs SSL termination.

To change the web server ports, the following environment variables can be set:

UC_API_HTTP_PORT=8000
UC_API_HTTPS_PORT=9000

Enable / disable http or https:

UC_API_HTTP_ENABLED=false
UC_API_HTTPS_ENABLED=true

FontAwesome6 fonts for Web-Configurator

The Simulator includes the free version of Font Awesome 6. The real Remote device is shipped with a licensed Pro version.
Many icons are missing in the free version and therefore not available in the web-configurator of the Simulator.

If you have a Pro license of Font Awesome 6, you can put the font files into the ./fontawesome6 subdirectory to get the same icons as with a Remote device. See docker-compose.yml for required font files and how to enable the volume mapping.

Certificates

Certificates for the TLS connection can be specified with environment variables:

UC_CERTS_PUBLIC=./data/certs/public.pem
UC_CERTS_PRIVATE=./data/certs/private.pem

Use mkcert for easy local development with self-signed certificates.

Set UC_INTEGRATION_DISABLE_CERT_VERIFICATION=true to disable verification.

Logging

The log level of the Simulator can be changed through the environment variable RUST_LOG=debug.
Valid log levels are: debug, info, warn, error.

Attention: debug logging is very verbose, especially mdns messages! Specific categories can be overridden or excluded. Examples:

  • Set debug logging only for integration module: RUST_LOG=info,remote_core::intg=debug
  • Exclude mdns: RUST_LOG=debug,mdns_sd=info

Core-Simulator WebSocket Core-API message tracing

Container core-simulator:

  • Set ENV variable UC_API_MSG_TRACING to enable Core-API WebSocket message tracing.
  • Set ENV variable UC_INTG_MSG_TRACING to enable WebSocket Dock and Integration-API message tracing.

Message tracing is logged as debug level.

Values:

  • all: enables incoming and outgoing message tracing
  • in: incoming messages only
  • out: outgoing messages only

⚠️ Warning: no message filtering is performed. Exchanged secrets like tokens or pins are exposed with this setting!

Home Assistant integration WebSocket message tracing

Container integration-hass:

  • Set ENV variable UC_API_MSG_TRACING to enable Core-API WebSocket message tracing.
  • Set ENV variable UC_HASS_MSG_TRACING to enable Home Assistant WS message tracing.

The same values are used as above.

Home Assistant Voice Assistant Setup

The Docker compose setup already includes the Speech-to-Phrase image required for Home Assistant.

Add Wyoming Protocol Integration

  1. Go to Settings, Devices & services
  2. Add Integration
  3. Search for Wyoming Protocol and add it:
    • Host: speech-to-phrase
    • Port: 10300

Configure Voice Assistant

  1. Go to Settings, Voice assistants
  2. If the Assist list is empty: add assistant, otherwise edit the default entry
  3. For Speech-to-text select speech-to-phrase.

Important

The Speech-to-text configuration is required to enable the voice_assistant entity. Otherwise the Home Assistant voice assistant entity will not be available.

Remote-UI

To connect the remote-ui application with the Simulator, the app requires access to the dynamically created token file in ./ui-env/ws-token. This file path must be specified in the environment variable UC_TOKEN_PATH.

Linux example:

UC_TOKEN_PATH=/home/projects/core-simulator/docker/ui-env/ws-token remote-ui

macOS example:

UC_TOKEN_PATH=/Users/projects/core-simulator/docker/ui-env/ws-token Remote\ UI.app/Contents/MacOS/Remote\ UI