# Build the Amazon IoT Greengrass container image from a Dockerfile
<a name="build-greengrass-dockerfile"></a>

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
<a name="download-dockerfile-package"></a>

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

[AWS Greengrass Docker Repository](https://github.com/aws-greengrass/aws-greengrass-docker)

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
<a name="set-dockerfile-build-argument"></a>

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
<a name="set-dockerfile-environment-variables"></a>

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](https://docs.docker.com/engine/reference/commandline/run/#env) 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](https://docs.docker.com/compose/environment-variables/).

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.   
+ If you specify `true`, Amazon IoT Greengrass Core software registers the container image as an Amazon IoT thing and provisions the Amazon resources that the Greengrass core device requires. The Amazon IoT Greengrass Core software provisions an Amazon IoT thing, (optional) an Amazon IoT thing group, an IAM role, and an Amazon IoT role alias. For more information, see [Run Amazon IoT Greengrass in a Docker container with automatic resource provisioning](run-greengrass-docker-automatic-provisioning.md).
+ If you specify `false`, then you must create a configuration file to provide to the Amazon IoT Greengrass Core installer that specifies to use the Amazon resources and certificates that you manually created. For more information, see [Run Amazon IoT Greengrass in a Docker container with manual resource provisioning](run-greengrass-docker-manual-provisioning.md).
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](device-service-role.md).  
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\$1user:ggc\$1group** or **ggc\$1user**.  
+ 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](configure-greengrass-core-v2.md#configure-component-user).

`DEPLOY_DEV_TOOLS`  
Defines whether to download and deploy the [Greengrass CLI component](greengrass-cli-component.md) in the container image. You can use the Greengrass CLI to develop and debug components locally.  
 <a name="local-dev-tools-production-environment-warning"></a>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](greengrass-nucleus-component.md).  
(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](fleet-provisioning.md) or [custom provisioning](custom-provisioning.md). 

`THING_POLICY_NAME`  
This feature is available for v2.4.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).  
(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.  
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](device-auth.md#greengrass-core-minimal-iot-policy). 

## Specify the dependencies to install
<a name="dockerfile-run-instruction"></a>

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
<a name="build-greengrass-docker-image"></a>

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
   ```

1. 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
   ```

1. 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.