The Carbon Engine environment variables
Carbon Engine is configured by passing in environment variables to the container.
Core functionality
| Environment variable | Required | Description |
|---|---|---|
| COGO_LICENSE | Yes | The Carbon Engine license key provided by Cogo. This key is valid for a set time period and contains authentication information to retrieve climate data from the Cogo Climate Data API. Carbon Engine will not start without a valid license key. |
| COGO_AUTHENTICATION_MODE | Yes | Set to one of none, static, or jwt. See Authentication Functionality below. |
| TZ | No | If set, uses the specified time zone when retrieving today's current date for date-based logic. If not set, defaults to UTC. |
| INSTANCE_ID | No | If set, will include the INSTANCE_ID value in the metadata of any generated log messages |
Authentication functionality
Carbon Engine offers two authentication methods, a static shared secret or JWT validation. Authentication can also be disabled.
If using the storage mode of the Carbon Engine, it is highly recommended that endpoints are protected by authentication.
Refer to the Security documentation for more information.
| Environment variable | Required | Description |
|---|---|---|
| COGO_HASHED_ACCESS_KEY | If COGO_AUTHENTICATION_MODE is static |
The base-64 encoded SHA-256 of a static shared secret that must be present on all requests in the Authentication HTTP header |
| COGO_JWT_ISSUER | If COGO_AUTHENTICATION_MODE is jwt |
The issuer that must match the iss field in valid JWTs |
| COGO_JWKS_URL | If COGO_AUTHENTICATION_MODE is jwt |
The URL of the jwks.json file which contains a JWK matching the kid field in valid JWTs |
| COGO_JWT_SUBS | No | When COGO_AUTHENTICATION_MODE is jwt, can optionally pass a space separated list of JWT subs. Tokens must match at least one of the specified subs. |
| COGO_JWT_REQUIRED_SCOPE | No | When COGO_AUTHENTICATION_MODE is jwt, can optionally pass a required scope. Tokens must include the required scope. |
Climate data access configuration
Cogo climate data includes all the information required to recognise expenditure categories, footprint transactions with emissions factors, provide survey questions to users to understand their behaviour, and calculate quantified climate action savings.
Data is retrieved directly from the Cogo Climate Data API using credentials found in your license key, or can be provided directly as a file to the Carbon Engine.
Refer to the Climate data access documentation for more information about these settings.
| Environment variable | Required | Description |
|---|---|---|
| COGO_DATAPACK | No | If you want to run the Carbon Engine with egress network access disabled, provide a path to a Cogo climate datapack in this environment variable. The path must be accessible from inside the container, so a volume must be mounted to make it available. Setting this variable will prevent the Carbon Engine from connecting to the Cogo climate data API. |
| COGO_DATAPACK_CACHE | Recommended | The Carbon Engine connects to the Climate Data API every time it starts up, and will exit with an error code if the API is not available. Specifying a file path (e.g. /mnt/data/cache.datapack) or AWS S3 path (e.g. s3:bucket-name/path/cache.datapack) in this variable will cause the Carbon Engine to write received climate data to the path and retrieve it from the path if API access is unavailable.For the cache to be persistent across restarts, ensure it is saved either to S3 or a persistent volume mounted into the container. |
| COGO_REVISION_ID | No | If set, the Carbon Engine will request a specific revision from the Climate Data API. If not set, it will retrieve the latest published revision. This enables clients to stay on a legacy revision of the climate data until they have performed analysis of the latest revision. |
Storage functionality
Storage environment variables are optional and only required if the storage facilities of the Carbon Engine are to be used.
Refer to the Storage with AWS documentation for more information about these settings.
| Environment variable | Required to enable storage | Description |
|---|---|---|
| COGO_STORAGE | Yes | A URI that specifies the service and location to load and store user transaction and response information. Either in the format:s3:BUCKET-NAME?locking=dynamo&table=TABLE-NAMEor path:///path/to/storage?locking=dynamo&table=TABLE-NAMEAppend &custom_fields=field1,field2 to specify custom fields. |
| AWS_ACCESS_KEY_ID | No | AWS access key ID for accessing S3 and DynamoDB. If not specified, the Carbon Engine will use the task role if running inside ECS, or the instance role otherwise. |
| AWS_SECRET_ACCESS_KEY | No | AWS secret access key for accessing S3 and DynamoDB. If not specified, the Carbon Engine will use the task role if running inside ECS, or the instance role otherwise. |
| AWS_REGION | Yes | Region that the AWS services are running in. |
| AWS_POOL_SIZE | No | Sets the maximum number of workers available to make AWS requests. Defaults to 50. If running on a 32+ core machine and CPU load is not being maximally used then consider increasing this number. |
Event streaming functionality
Event streaming environment variables are optional and only required if Event Streaming is enabled. Refer to the Event streaming with AWS documentation for more information about these settings.
The COGO_STORAGE environment variable specified in the storage functionality section above is also required, and must point to an S3 bucket.
| Environment variable | Required to enable event streaming | Description |
|---|---|---|
| COGO_S3_EVENT_QUEUE | Yes | An S3 queue in URL format which is configured to have S3 "Put" events published to it |
| COGO_BUSINESS_EVENT_SINK | Yes | The name of an EventBridge bus to which business events will be published |
User namespacing
Multiple systems with potentially conflicting user IDs can be run off a single Carbon Engine instance using user namespacing.
By default, requests use the "default" user namespace. However, by providing an HTTP header, X-User-Namespace,
a different namespace can be selected. This HTTP header is by default optional, but there is a configuration
option that requires all requests that interact with users must have a user namespace explicitly defined.
Refer to the User namespaces documentation for more information about this setting.
| Environment variable | Required | Description |
|---|---|---|
| COGO_REQUIRE_USER_NAMESPACE | No | When set to true, requires a X-User-Namespace HTTP header on every user-interacting request. Defaults to false. |
Carbon Budget functionality
Carbon budget environment variables are optional.
The date rounding strategy applies to monthly periods where the selected period_start_day_of_month is not present in that month. For example, if period_start_day_of_month = 30 then a rounding strategy needs to be applied to February, as 30th February is never a valid date.
| Rounding strategy | Period start day of month | Example periods when period_start_day_of_month = 30 |
|---|---|---|
down |
Rounded down to the last day of the month. | Jan 30 - Feb 27 Feb 28 - Mar 29 Mar 30 - Apr 29 |
up |
Rounded up to the first day of the following month. | Jan 30 - Feb 28 Mar 1 - Mar 29 Mar 30 - Apr 29 |
previous_weekday |
Rounded down to the nearest weekday. | Varies |
previous_weekday_including_holidays |
Rounded down to the nearest non-holiday weekday. | Varies |
| Environment variable | Required | Description |
|---|---|---|
| COGO_DATE_ROUNDING_STRATEGY | No | The selected date rounding strategy. Options are: down, up, or previous_weekday. Defaults to down. |
| COGO_DATE_HOLIDAY_REGION | No | The selected date holiday region. Talk to your Cogo representative to add holidays for your region. |
Logger Level
The logger level can be customised to control the severity of messages that are logged to the console. By default, any messages at info or higher are logged. The available logger levels are:
errorwarninginfodebug- will print Personally Identifiable Information (PII) to the console
To customise the logger level, set the LOGGER_LEVEL environment variable.