dcbr/hass-custom-devcontainer repository overview

⁠A docker container for developing and testing custom Home Assistant plugins and integrations

⁠Usage

docker run --rm -it \
    -p 5000:8123 \
    -v $(pwd)/test:/workspace/test \
    -v $(pwd)/dist:/workspace/dist \
    -v $(pwd)/custom_components:/workspace/custom_components \
    -e LOVELACE_PLUGINS="thomasloven/lovelace-card-mod;custom-cards/button-card" \
    dcbr/hass-custom-devcontainer

The default action of the image is to run container, which will

• Make sure there's a basic Home Assistant configuration in /config based on the test configuration provided in the workspace (/workspace/test/config).
• Add a default admin user to Home Assistant.
• Skip the onboarding procedure.
• Download and install HACS⁠ (optionally).
• Download lovelace plugins from github (optionally).
• Add downloaded and local plugins to lovelace configuration. The local plugins are fetched from the distribution folder in the workspace (/workspace/dist).
• Add local integrations to the configuration. The local integrations are fetched from the custom components folder in the workspace (/workspace/custom_components).
• Start Home Assistant with -v.

⁠Changelog

This is a fork from thomasloven/hass-custom-devcontainer⁠ with following changes:

• Updated python environment and dependencies
• Auto discovery and installation of locally developed plugins and integrations mounted in the /workspace/dist and /workspace/custom_components folders
• Test configuration files mounted in the /workspace/test/config folder are preprocessed and copied to /config to be used by Home Assistant
• Added support for bypassing the login form and for trusting the specified proxies
• Built-in support for running this container as a codespace (see below)

⁠Environment Variables

⁠Mount Points

A /workspace volume is set up to make local files available in the container. More specifically, all test related files can be mounted in /workspace/test, all locally built javascript modules (plugins) can be mounted in /workspace/dist and all locally developed python modules (integrations) can be mounted in /workspace/custom_components.

Custom configuration files for Home Assistant should be placed inside the config folder of the test mount point. Note that the configuration file might be modified while launching the container, depending on the value of certain environment variables. To avoid unwanted modifications to your ogininal configuration file, the contents of /workspace/test/config are copied to /config before starting Home Assistant. Similarly the contents of the /workspace/dist folder are copied to /config/www/workspace and the contents of the /workspace/custom_components folder are copied to /config/custom_components. When the container script is launched, each mount point is continuously watched for any changes. These changes are then immediately reflected in Home Assistant's configuration folder.

Note: When working in a codespace, the active workspace files can be bound through the CODESPACE_PLUGINS, CODESPACE_INTEGRATIONS and CODESPACE_TEST environment variables.

⁠About Lovelace Plugins

The dowload and installation of plugins is very basic. This is not HACS.

LOVELACE_PLUGINS should be a semicolon separated list of author/repo pairs, e.g. thomasloven/lovelace-card-mod;kalkih/mini-media-player

Any locally developed javascript modules mounted in /workspace/dist are also installed.

⁠About Integrations

If a locally developed integration is not manually configured in the test configuration, it is automatically added.

⁠Container Script

container

Set up and launch Home Assistant

container setup

Perform download and setup parts but do not launch Home Assistant

container launch

Launch Home Assistant with hass -c /config -v

⁠devcontainer.json example

{
  "image": "dcbr/hass-custom-devcontainer",
  "postCreateCommand": "sudo -E container setup && npm add",
  "postStartCommand": "sudo -E container launch",
  "forwardPorts": [8123],
  "mounts": [
    "source=${localWorkspaceFolder},target=/workspace,type=bind,readonly"
  ],
  "runArgs": ["--env-file", "${localWorkspaceFolder}/test/test.env"]
}

⁠Github codespace example

{
  "image": "dcbr/hass-custom-devcontainer",
  "postCreateCommand": "sudo -E container setup && npm add",
  "postStartCommand": "sudo -E container launch",
  "forwardPorts": [8123],
  "containerEnv": {
    "CODESPACE_INTEGRATIONS": "${localWorkspaceFolder}/integration",
    "CODESPACE_PLUGINS": "${localWorkspaceFolder}/es",
    "CODESPACE_TEST": "${localWorkspaceFolder}/test",
    "ENV_FILE": "${localWorkspaceFolder}/test/test.env"
  }
}

See also dcbr/ha-templated-card⁠ for an example repository.