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.
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.
If you need examples of our regional packet forwarder configurations, please see here.
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