Run Amazon IoT Greengrass Core software in a Docker container - Amazon IoT Greengrass
Supported platforms and requirementsSoftware downloadsChoose how to provision Amazon resources
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).

Run Amazon IoT Greengrass Core software in a Docker container

Amazon IoT Greengrass can be configured to run in a Docker container. Docker is a platform that provides the tools for you to build, run, test, and deploy applications that are based on Linux containers. When you run an Amazon IoT Greengrass Docker image, you can choose whether to provide your Amazon credentials to the Docker container and allow the Amazon IoT Greengrass Core software installer to automatically provision the Amazon resources that a Greengrass core device requires to operate. If you don't want to provide Amazon credentials, then you can manually provision Amazon resources and run Amazon IoT Greengrass Core software in the Docker container.

Topics

Supported platforms and requirements

Host computers must meet the following minimum requirements to install and run the Amazon IoT Greengrass Core software in a Docker container:

  • A Linux-based operating system with an internet connection.

  • Docker Engine version 18.09 or later.

  • (Optional) Docker Compose version 1.22 or later. Docker Compose is required only if you want to use the Docker Compose CLI to run your Docker images.

To run Lambda function components inside of the Docker container, you must configure the container to meet additional requirements. For more information, see Lambda function requirements.

Run components in process mode

Amazon IoT Greengrass doesn't support running Lambda functions or Amazon-provided components in an isolated runtime environment inside the Amazon IoT Greengrass Docker container. You must run these components in process mode without any isolation.

When you configure a Lambda function component, set the isolation mode to No container. For more information, see Run Amazon Lambda functions.

When you deploy any of the following Amazon-provided components, update the configuration for each component to set the containerMode parameter to NoContainer. For more information about configuration updates, see Update component configurations.

Amazon IoT Greengrass Docker software downloads

Amazon IoT Greengrass provides a Dockerfile to build a container image that has Amazon IoT Greengrass Core software and dependencies installed on an Amazon Linux 2 (x86_64) base image. You can modify the base image in the Dockerfile to run Amazon IoT Greengrass on a different platform architecture.

Download the Dockerfile package from GitHub.

The Dockerfile uses an older version of Greengrass. You should update the file to use the version of Greengrass that you want. For information about building the Amazon IoT Greengrass container image from the Dockerfile, see Build the Amazon IoT Greengrass container image from a Dockerfile.

Choose how to provision Amazon resources

When you install the Amazon IoT Greengrass Core software in a Docker container, you can choose whether to automatically provision the Amazon resources that a Greengrass core device requires to operate, or to use resources that you manually provision.

  • Automatic resource provisioning—The installer provisions the Amazon IoT thing, Amazon IoT thing group, IAM role, and Amazon IoT role alias when you run the Amazon IoT Greengrass container image for the first time. The installer can also deploy the local development tools to the core device, so you can use the device to develop and test custom software components. To automatically provision these resources, you must provide Amazon credentials as environment variables to the Docker image.

    To use automatic provisioning, you must set the Docker environment variable PROVISION=true and mount a credential file to provide your Amazon credentials to the container.

  • Manual resource provisioning—If you don't want to provide Amazon credentials to the container, then you can manually provision the Amazon resources before you run the Amazon IoT Greengrass container image. You must create a configuration file to provide information about these resources to the Amazon IoT Greengrass Core software installer within the Docker container.

    To use manual provisioning, you must set the Docker environment variable PROVISION=false. Manual provisioning is the default option.

For more information, see Build the Amazon IoT Greengrass container image from a Dockerfile.