Build the Amazon IoT Greengrass container image from a Dockerfile - Amazon IoT Greengrass
Download the Dockerfile packageSpecify the software versionSet environment variablesSpecify the dependencies to installBuild the Amazon IoT Greengrass image
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Build the Amazon IoT Greengrass container image from a Dockerfile

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

Before you build an Amazon IoT Greengrass container image, you must configure your Dockerfile to select the version of Amazon 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 Amazon IoT Greengrass Docker image from a Dockerfile.

Download the Dockerfile package

You can download the Amazon 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 Amazon IoT Greengrass Core software version

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

GREENGRASS_RELEASE_VERSION

The version of the Amazon 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 Amazon IoT Greengrass Core software is installed in the Docker container. You can set environment variables for your Amazon 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 Amazon 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 Amazon 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 Amazon IoT Greengrass Core software.

Default: /greengrass/v2

PROVISION

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

Default: false

AWS_REGION

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

Default: us-east-1.

THING_NAME

(Optional) The name of the Amazon IoT thing that you register as this core device. If the thing with this name doesn't exist in your Amazon Web Services account, the Amazon 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 Amazon IoT thing group where you add this core device's Amazon IoT If a deployment targets this thing group, this and other core devices in that group receive that deployment when it connects to Amazon IoT Greengrass. If the thing group with this name doesn't exist in your Amazon Web Services account, the Amazon 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 Amazon credentials that let the Greengrass core device interact with Amazon services. If the role with this name doesn't exist in your Amazon Web Services account, the Amazon 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 Amazon services.

Default: GreengrassV2TokenExchangeRole

TES_ROLE_ALIAS_NAME

(Optional) The name of the Amazon IoT role alias that points to the IAM role that provides Amazon credentials for the Greengrass core device. If the role alias with this name doesn't exist in your Amazon Web Services account, the Amazon 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 Amazon 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 Amazon IoT Greengrass Core software uses that user to run components.

  • If you don't specify a group, the Amazon 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 Amazon 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 Amazon IoT policy to attach to this core device's Amazon IoT thing certificate. If the Amazon IoT policy with this name doesn't exist in your Amazon Web Services account the Amazon IoT Greengrass Core software creates it.

You must specify PROVISION=true to apply this argument.

Note

The Amazon IoT Greengrass Core software creates a permissive Amazon 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 Amazon IoT policy for Amazon IoT Greengrass V2 core devices.

Specify the dependencies to install

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

Build the Amazon IoT Greengrass image

Use the Amazon IoT Greengrass Dockerfile to build an Amazon 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 Amazon 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 Amazon IoT Greengrass container image.

    docker-compose -f docker-compose.yml build

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