Run AWS IoT Greengrass Core software in a Docker container - AWS IoT Greengrass
Supported platforms and requirementsSoftware downloadsChoose how to provision AWS resources

Run AWS IoT Greengrass Core software in a Docker container

AWS 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 AWS IoT Greengrass Docker image, you can choose whether to provide your AWS credentials to the Docker container and allow the AWS IoT Greengrass Core software installer to automatically provision the AWS resources that a Greengrass core device requires to operate. If you don't want to provide AWS credentials, then you can manually provision AWS resources and run AWS 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 AWS 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

AWS IoT Greengrass doesn't support running Lambda functions or AWS-provided components in an isolated runtime environment inside the AWS 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 AWS Lambda functions.

When you deploy any of the following AWS-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.

AWS IoT Greengrass Docker software downloads

AWS IoT Greengrass provides a Dockerfile to build a container image that has AWS 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 AWS 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 AWS IoT Greengrass container image from the Dockerfile, see Build the AWS IoT Greengrass container image from a Dockerfile.

Choose how to provision AWS resources

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

  • Automatic resource provisioning—The installer provisions the AWS IoT thing, AWS IoT thing group, IAM role, and AWS IoT role alias when you run the AWS 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 AWS 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 AWS credentials to the container.

  • Manual resource provisioning—If you don't want to provide AWS credentials to the container, then you can manually provision the AWS resources before you run the AWS IoT Greengrass container image. You must create a configuration file to provide information about these resources to the AWS 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 AWS IoT Greengrass container image from a Dockerfile.