Build the AWS IoT Greengrass container image from a Dockerfile - AWS IoT Greengrass
Download the Dockerfile packageSpecify the software versionSet environment variablesSpecify the dependencies to installBuild the AWS IoT Greengrass image

Build the AWS IoT Greengrass container image from a Dockerfile

AWS provides a Dockerfile that you can download and use to run AWS IoT Greengrass Core software in a Docker container. Dockerfiles contain source code for building AWS IoT Greengrass container images.

Before you build an AWS IoT Greengrass container image, you must configure your Dockerfile to select the version of AWS IoT Greengrass Core software that you want to install. You can also configure environment variables to choose how to provision resources during installation, and customize other installation options. This section describes how to configure and build an AWS IoT Greengrass Docker image from a Dockerfile.

Download the Dockerfile package

You can download the AWS IoT Greengrass Dockerfile package from GitHub:

AWS Greengrass Docker Repository

After you download the package, extract the contents to the download-directory/aws-greengrass-docker-nucleus-version folder on your computer. The Dockerfile uses an older version of Greengrass. You should update the file to use the version of Greengrass that you want.

Specify the AWS IoT Greengrass Core software version

Use the following build argument in the Dockerfile to specify the version of the AWS IoT Greengrass Core software that you want to use in the AWS IoT Greengrass Docker image. By default, the Dockerfile uses the latest version of the AWS IoT Greengrass Core software.

GREENGRASS_RELEASE_VERSION

The version of the AWS IoT Greengrass Core software. By default, the Dockerfile downloads the latest available version of the Greengrass nucleus. Set the value to the version of the nucleus that you want to download.

Set environment variables

Environment variables enable you to customize how AWS IoT Greengrass Core software is installed in the Docker container. You can set environment variables for your AWS IoT Greengrass Docker image in various ways.

  • To use the same environment variables to create multiple images, set environment variables directly in the Dockerfile.

  • If you use docker run to start your container, pass environment variables as arguments in the command, or set environment variables in an environment variables file and then pass the file as an argument. For more information about setting environment variables in Docker, see the environment variables in the Docker documentation.

  • If you use docker-compose up to start your container, set environment variables in an environment variables file and then pass the file as an argument. For more information about setting environment variables in Compose, see the Docker documentation.

You can configure the following environment variables for the AWS IoT Greengrass Docker image.

Note

Don't modify the TINI_KILL_PROCESS_GROUP variable in the Dockerfile. This variable allows forwarding SIGTERM to all PIDs in the PID group so that AWS IoT Greengrass Core software can shut down correctly when the Docker container is stopped.

GGC_ROOT_PATH

(Optional) The path to the folder within the container to use as the root for AWS IoT Greengrass Core software.

Default: /greengrass/v2

PROVISION

(Optional) Determines whether the AWS IoT Greengrass Core provisions AWS resources.

Default: false

AWS_REGION

(Optional) The AWS Region that the AWS IoT Greengrass Core software uses to retrieve or create required AWS resources.

Default: us-east-1.

THING_NAME

(Optional) The name of the AWS IoT thing that you register as this core device. If the thing with this name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it.

You must specify PROVISION=true to apply this argument.

Default: GreengrassV2IotThing_ plus a random UUID.

THING_GROUP_NAME

(Optional) The name of the AWS IoT thing group where you add this core device's AWS IoT If a deployment targets this thing group, this and other core devices in that group receive that deployment when it connects to AWS IoT Greengrass. If the thing group with this name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it.

You must specify PROVISION=true to apply this argument.

TES_ROLE_NAME

(Optional) The name of the IAM role to use to acquire AWS credentials that let the Greengrass core device interact with AWS services. If the role with this name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it with the GreengrassV2TokenExchangeRoleAccess policy. This role doesn't have access to your S3 buckets where you host component artifacts. So, you must add permissions to your artifacts' S3 buckets and objects when you create a component. For more information, see Authorize core devices to interact with AWS services.

Default: GreengrassV2TokenExchangeRole

TES_ROLE_ALIAS_NAME

(Optional) The name of the AWS IoT role alias that points to the IAM role that provides AWS credentials for the Greengrass core device. If the role alias with this name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it and points it to the IAM role that you specify.

Default: GreengrassV2TokenExchangeRoleAlias

COMPONENT_DEFAULT_USER

(Optional) The name or ID of the system user and group that the AWS IoT Greengrass Core software uses to run components. Specify the user and group, separated by a colon. The group is optional. For example, you can specify ggc_user:ggc_group or ggc_user.

  • If you run as root, this defaults to the user and group that the configuration file defines. If the configuration file doesn't define a user and group, this defaults to ggc_user:ggc_group. If ggc_user or ggc_group don't exist, the software creates them.

  • If you run as a non-root user, the AWS IoT Greengrass Core software uses that user to run components.

  • If you don't specify a group, the AWS IoT Greengrass Core software uses the primary group of the system user.

For more information, see Configure the user that runs components.

DEPLOY_DEV_TOOLS

Defines whether to download and deploy the Greengrass CLI component in the container image. You can use the Greengrass CLI to develop and debug components locally.

Important

We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it.

Default: false

INIT_CONFIG

(Optional) The path to the configuration file to use to install the AWS IoT Greengrass Core software. You can use this option to set up new Greengrass core devices with a specific nucleus configuration, or to specify manually provisioned resources, for example. You must mount your configuration file to the path that you specify in this argument.

TRUSTED_PLUGIN

This feature is available for v2.4.0 and later of the Greengrass nucleus component.

(Optional) The path to a JAR file to load as a trusted plugin. Use this option to provide provisioning plugin JAR files, such as to install with fleet provisioning or custom provisioning.

THING_POLICY_NAME

This feature is available for v2.4.0 and later of the Greengrass nucleus component.

(Optional) The name of the AWS IoT policy to attach to this core device's AWS IoT thing certificate. If the AWS IoT policy with this name doesn't exist in your AWS account the AWS IoT Greengrass Core software creates it.

You must specify PROVISION=true to apply this argument.

Note

The AWS IoT Greengrass Core software creates a permissive AWS IoT policy by default. You can scope down this policy, or create a custom policy where you restrict permissions for your use case. For more information, see Minimal AWS IoT policy for AWS IoT Greengrass V2 core devices.

Specify the dependencies to install

The RUN instruction in the AWS IoT Greengrass Dockerfile prepares up the container environment to run the AWS IoT Greengrass Core software installer. You can customize the dependencies that are installed before the AWS IoT Greengrass Core software installer runs in the Docker container.

Build the AWS IoT Greengrass image

Use the AWS IoT Greengrass Dockerfile to build an AWS IoT Greengrass container image. You can use the Docker CLI or the Docker Compose CLI to build the image and start the container. You can also use the Docker CLI to build the image and then use Docker Compose to start your container from that image.

Docker

  1. On the host machine, run the following command to switch to the directory that contains the configured Dockerfile.

    cd download-directory/aws-greengrass-docker-nucleus-version

  2. Run the following command to build the AWS IoT Greengrass container image from the Dockerfile.

    sudo docker build -t "platform/aws-iot-greengrass:nucleus-version" ./
Docker Compose

  1. On the host machine, run the following command to switch to the directory that contains the Dockerfile and the Compose file.

    cd download-directory/aws-greengrass-docker-nucleus-version

  2. Run the following command to use the Compose file to build the AWS IoT Greengrass container image.

    docker-compose -f docker-compose.yml build

You have successfully created the AWS IoT Greengrass container image. The Docker image has the AWS IoT Greengrass Core software installed. You can now run the AWS IoT Greengrass Core software in a Docker container.