> This page is a work in progress and anything here may be changed in the future.
> The information here is an attempt of documentation driven development and may not be actually implemented in code yet

# ¶ Environment Variables

Balena makes extensive use of Environment and Service variables to manage a fleet of devices.
Environment variables apply to the whole device. Service variables apply just to one service.
Variables can be applied per device or across the whole fleet of devices.

Variables can be set using `docker-compose` files, through the Balena Cloud web interface or using the python SDK.

Read the Balena Environment Variable Documentation before going further.

# ¶ Enabling / Disabling Services

The system has a number of different services running in seperate containers - for example - `sunspec`, `huawei`, etc.
Some of these services will not be needed by all CoFyBox users and should be specifically enabled.

COFYBOX_ENABLE_SERVICE
Each service can be turned on or off using the correct service variables. Service variables only apply to on a per service level.
A service will run when an environment variable `COFYBOX_ENABLE_SERVICE` is set to true for that service.
It is not recommended to use this to turn off some 'essential' services in this way: `mosquitto`, `homeassistant`, `glue`, `telegraf`, `configurator` and `nginx-reverse-proxy`. If you wish to be able to turn these off, you will first need to change their restart policies in docker-compose to `restart: on-failure`.

### ¶ How to toggle variables

Environment variables can be altered in the Balena cloud by going to Fleets > Cofybox-production > the device in question > "Device Variables"

## ¶ Future Development - Getting block configuration from CoFyCloud

> Only a suggestion - not implemented

The CoFyBox connects to the CoFyCloud for provisioning. At this stage it downloads a set of configuration variables.
These configuraton variables are applied to the device using the Balena SDK.

### ¶ Settings payload format

The format of the settings payload coming from the API could look something like this:

    {
      "blocks_enabled": [
        { "cofycloud": true },
        { "homeassistant": true },
        { "mosquitto": true },
        { "wifi-hotspot": true },
        { "telegraf": true },
        { "glue-component": true },
        { "sunspec": false },
      ]
    }

# ¶ Configuring Services

Some services require a complex set of configuration options. The environment variables method is probably not appropriate.

For the current state of development, a configuration `yaml` file is useful to store configuration settings for each block. The settings format will likely need to change often, so a user friendly interface is not necessary at this point of development.

Instead, a new block - `configurator` - is used to edit these yaml files.
The block runs a modified version of hass-configurator - a program designed to edit Home Assistant configuration files.
A shared volume called `cofybox-config` is mounted into all blocks that require settings configuration.
This volume is also mounted into the `configurator` block.
Configuration `.yaml` files are stored in this volume. When a block initially starts, it copies a default configuration file into this volume, if one is not already present.

Details of each configuration file should be documented as part of the Services documentation.

To access the configurator interface, go to `http://<Address of CoFyBox>/configurator` (or `http://<IP of CoFyBox>:3218`).

When you have finished editing files you must restart the CoFyBox. This can be done with the Balena front end, CLI, ssh connection to the Host OS, or via the Cofycloud. It may be possible to enable this to be done from the configurator interface (`HC_HASS_API` is currently set to None, so it is not currently possible).

# ¶ Configuration via MQTT

To read about steps towards developing a GUI and other more user-friendly features for editing settings, see Configuration via MQTT