Skip to main content

Docker Integration

We generally recommend that Makers use Docker for running Miner. This allows you to pull images from Helium's Quay repository and avoids the need to maintain your own Miner build & release pipeline along with all of Miner's system dependencies, such as Erlang.

If you prefer, you can build Miner from source, but this guide is for those that are running the Docker image.

The Docker Release Process

Before we get into the details, it's useful to understand how the Quay releases integrate with the Miner release flow.

Helium maintains the Miner repository and maintains proprietary firmware images for the original Helium Hotspots (Raspberry Pi 3B+ and 4 based). When we have a release candidate, you will see a tag with the date of the release candidate. This usually means that we are testing a release candidate. This testing process has many stages, but if and when a release passes, it will graduate to "General Availability" and be re-tagged with the _GA suffix. This triggers an automatic build of the Docker images which get pushed to Quay when complete.

In addition, a "Blockchain Release" will typically be posted on engineering.helium.com.

As a blockchain is decentralized in its nature, we are careful not to do breaking changes that require immediate and synchronized updates of the Miner.

When breaking changes need to be deployed, they tend to be gated by a "chain variable" (aka chainvar) which signals to the Miners that the new behavior is to take affect. Only when this chain variable is activated do stale Miners stop working.

info

It is highly recommended that Makers automate the process by checking the Quay repository for _GA tags every half hour, and plan on deploying at least once a day in case there are emergency releases.

Initial Testing of the Docker on Your Host System

The Docker image is tailored to be able to run very simply at first, but will generally require additional customization to integrate well with your host system.

Start by following these instructions. If that ends up being no problem, then you're doing great! The extra sections in this guide will discuss things you should do when preparing a production system for the Miner container.

Omit REGION_OVERRIDE

Setting REGION_OVERRIDE is only useful if you want a hotspot to forward packets without being asserted on-chain (ie: they will not earn HNT). In a production system, the override can be detrimental as it will lock the device into that specific region. Instead, if you omit the override, the Miner watches the blockchain to figure out which region it has been asserted in.

In fact, in Helium's own firwmare image, we actually use this information to also determine which packet forwarder configuration to select, so our startup routine for packet forwarder will actually block as it requests region from miner

# Wait until miner knows the regulatory region.
while ! /opt/miner/bin/miner info region > /dev/null 2>&1; do
    sleep 1
done

This allows you to ship a single firmware image that will work in any region. When the user has asserted the Miner and its location to the blockchain, you can get the appropriate region from Miner and use the appropriate configuration for a packet forwarder.

info

If you need examples of our regional packet forwarder configurations, please see here.

warning

If you are using our packet forwarder, be sure to customize the rssi_offset field for your particular concentrator design. Misconfiguring this value may result in decreased Proof-of-Coverage performance for your customers.

Enable ECC608 and D-Bus

Miner has a configuration file which exposes many useful variables. For example, Helium uses this to configure the "blessed snapshot" in our firmware which enables Miners to quickly sync their ledger to the height of the most recent snapshots. You benefit from this automatically when you use our Docker files.

However, our Docker images also disable the ECC608 and dbus by default. If you are using the ECC608 and use the BLE for setting up the hotspots, you need to re-anble them.

The default Docker overrides are seen here. We do a few things that make the image more portable, such as disabling D-bus ({use_ebus, false}) and the ECC608 ({key, undefined}).

As a Hotspot vendor using Docker, you will want to revert these sys.config overrides by simply deleting them. You can do this in a way that persists over Docker updates by maintaining your own configuration file outside of the Docker (similar to what we do with /var/data/).

For example, you can create a directory called "overlay" and copy the default override. You now you will have ~/overlay/docker.config.

Delete the D-bus line ({use_ebus, false}) and the ECC608 line ({key, undefined}) and the behavior will revert to that in the main configuration file where these are enabled.

You will also want to add a few arguments to your Docker run command which create the extra mount point for the config, connect the i2c-device to the Docker container, and connect D-bus to the Docker container. For example:

 --device /dev/i2c-1 \
 --net host \
 --privileged \
 -v /var/run/dbus:/var/run/dbus \
 --mount type=bind,source=/home/ubuntu/overlay/docker.config,target=/config/sys.config

Define the DBus Config

You'll want to install the Miner's DBus config, typically at: /etc/dbus-1/system.d/com.helium.Miner.conf

Setting the ulimit

Ensure the ulimit system is set to a minimum of 64000; anything lower will be insufficient but more is welcome.

You'll want to include the Docker run argument --ulimit nofile=64000:64000.

In addition, you'll need to verify that your Linux system allows for such file limits. For example,

$ ulimit -Sn
64000

If the host system does not allow for 64,000 file handles, then the docker run argument will not be sufficient.

Edit this page