Configuring climate data access

The Carbon Engine requires a climate datapack to recognise expenditure categories, footprint transactions with emissions factors, provide survey questions to users to understand their behaviour, and calculate quantified climate action savings. This datapack can be fetched from the Cogo Climate Data API using your license (Mode 1 & Mode 2), or you can provide a static datapack file directly (Mode 3).

Access modes

The Carbon Engine can handle climate data access in three modes:

  1. By default, the Carbon Engine connects to the Cogo Climate Data API hourly, to retrieve the latest emissions factors and climate actions data configured for your license.
  2. The Carbon Engine connects to the Cogo Climate Data API and requests only a specific revision of the climate actions data configured for your license.
  3. A Cogo climate actions datapack file is supplied directly to the Carbon Engine. In this mode, the Carbon Engine will not connect to the Climate Data API.

Mode 1: Retrieve latest climate data hourly

This mode is the default. Credential information for accessing the Cogo Climate Data API is embedded into your Carbon Engine license so no further configuration of the Carbon Engine is required.

You must ensure that the Carbon Engine is able to send outbound traffic to the Cogo Climate Data API.

Mode 2: Retrieve a specific revision of the climate data

Although Cogo recommends that you always use the latest revision available, you may wish to pin your Carbon Engine to a specific revision of climate data.

To use a specific revision, set the environment variable COGO_REVISION_ID to the revision you'd like to pin against. To use a different revision, your containers will need to be restarted with the environment variable changed or removed.

You must ensure that the Carbon Engine is able to send outbound traffic to the Cogo Climate Data API.

Mode 3: Datapack file manually loaded with no API access required

This mode is only recommended for environments where outbound traffic cannot be allowed, and therefore Carbon Engine will not be able to connect to the Cogo Climate Data API.

Request a Cogo climate data datapack from your Cogo representative, or if you have access to the Climate Data API you can download your datapack directly.

Store the datapack in a location that is then mounted into your Carbon Engine containers. Set the COGO_DATAPACK environment variable to point to the file location of the datapack inside your container - this will prevent outbound requests to the Climate Data API.

For example, if you stored the datapack file as /var/lib/cogo-datapack.json on your host machine, you could start your container using the following command:

docker run \
  -e COGO_AUTHENTICATION_MODE=none \
  -e COGO_LICENSE="license-here" \
  -e COGO_DATAPACK=/datapack.json \
  -v /var/lib/cogo-datapack.json:/datapack.json \
  -p 443:443 -p 80:80 --rm ghcr.io/consciousconsumers/carbon-engine

The datapack file will be reloaded once an hour. If you want to make changes to it, ensure the change is made atomically so there's no chance the file is empty when the next check is made. On UNIX systems, you can do this by moving the new file within the same filesystem rather than copying it into place:

mv downloads/new-datapack.json /var/lib/cogo-datapack.json

Configuring a datapack cache (highly recommended)

The Carbon Engine requires a climate datapack to start up. If the datapack cannot be loaded, the container will crash. This is by design, as footprints cannot be calculated without a datapack available.

It's recommended that a datapack cache is configured to store a copy of the most recent datapack received from the Cogo Climate Data API. In the case that the network or API is not available on container start up, Carbon Engine will fall back to using cached local version.

The cache may be stored either in an S3 bucket or on a persistent volume using your cloud provider with the writeable volume mounted in your container.

For an S3 cache, set the COGO_DATAPACK_CACHE environment variable to point to an S3 path, for example s3:bucket-name/path/cache.datapack. Storing the cache in the same bucket as user data is acceptable. We recommend you store the file in the root of the bucket with the name datapack.cache to avoid conflicts with user data files.

For a cache stored on a mounted persistent volume, set the COGO_DATAPACK_CACHE environment variable to point to a file on the mounted volume, for example /mnt/data/cache.datapack.