This tutorial shows you how to pull the latest AWS IoT Greengrass Docker image from Docker Hub and start the Docker container. You can use the Docker CLI or the Docker Compose CLI to run the AWS IoT Greengrass Core software image in a Docker container.
Docker
1. Run the following command to pull the latest AWS IoT Greengrass Docker image from Docker Hub.
docker pull amazon/aws-iot-greengrass:latest
2. Run the following command to start the Docker container. This command runs the Greengrass Docker image that you downloaded from Docker Hub. If you use a Docker image from a different source, replace amazon/aws-iot-greengrass:latest with the name of your Docker image.
docker run --rm --init -it --name aws-iot-greengrass \ -v path/to/greengrass-v2-credentials:/root/.aws/:ro \ --env-file .env \
-p 8883 \
amazon/aws-iot-greengrass:latest
This example command uses the following arguments for docker run:
• --rm. Cleans up the container when it exits.
• --init. Uses an init process in the container.
NoteThe --init argument is required to shut down AWS IoT Greengrass Core software when you stop the Docker container.
Run AWS IoT Greengrass in Docker with automatic provisioning
• -it. (Optional) Runs the Docker container in the foreground as an interactive process. You can replace this with the -d argument to run the Docker container in detached mode instead.
For more information, see Detached vs foreground in the Docker documentation.
• --name. Runs a container named aws-iot-greengrass
• -v. Mounts a volume into the Docker container to make the configuration file and the certificate files available to AWS IoT Greengrass running inside the container.
• --env-file. (Optional) Specifies the environment file to set the environment variables that will be passed to the AWS IoT Greengrass Core software installer inside the Docker container. This argument is required only if you created an environment file (p. 159) to set environment variables. If you didn't create an environment file, you can use --env arguments to set environment variables directly in your Docker run command.
• -p. (Optional) Publishes the 8883 container port to the host machine. This argument is required if you want to connect and communicate over MQTT because AWS IoT Greengrass uses port 8883 for MQTT traffic. To open other ports, use additional -p arguments.
NoteTo run your Docker container with increased security, you can use the --cap-drop and --cap-add arguments to selectively enable Linux capabilities for your container.
For more information, see Runtime privilege and Linux capabilities in the Docker documentation.
3. Remove the credential file from path/to/greengrass-v2-credentials.
Docker Compose
1. Use a text editor to create a Docker Compose file named docker-compose.yml.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the docker-compose.yml in the current directory.
nano docker-compose.yml
NoteYou can also download and use the latest version of the AWS-provided Compose file from GitHub.
2. Add the following content to the Compose file. Your file should look similar to the following example. This example specifies the Greengrass Docker image that you downloaded from Docker Hub. If you use a Docker image from a different source, replace amazon/aws-iot-greengrass:latest with the name of your Docker image.
version: '3.7' services:
greengrass:
init: true build:
context: .
container_name: aws-iot-greengrass image: amazon/aws-iot-greengrass:latest volumes:
- ./greengrass-v2-credentials:/root/.aws/:ro env_file: .env
ports:
- "8883:8883"
The following parameters in this example Compose file are optional:
Run AWS IoT Greengrass in Docker with automatic provisioning
• ports—Publishes the 8883 container ports to the host machine. This parameter is required if you want to connect and communicate over MQTT because AWS IoT Greengrass uses port 8883 for MQTT traffic.
• env_file—Specifies the environment file to set the environment variables that will be passed to the AWS IoT Greengrass Core software installer inside the Docker container. This parameter is required only if you created an environment file (p. 159) to set environment variables. If you didn't create an environment file, you can use the environment parameter to set the variables directly in your Compose file.
NoteTo run your Docker container with increased security, you can use cap_drop and cap_add in your Compose file to selectively enable Linux capabilities for your container. For more information, see Runtime privilege and Linux capabilities in the Docker documentation.
3. Run the following command start the Docker container.
docker-compose -f docker-compose.yml up
4. Remove the credential file from ./greengrass-v2-credentials.
Next steps
AWS IoT Greengrass Core software is now running in a Docker container. Run the following command to retrieve the container ID for the currently running container.
docker ps
You can then run the following command to access the container and explore AWS IoT Greengrass Core software running inside the container.
docker exec -it container-id /bin/bash
For information about creating a simple component, see Step 4: Develop and test a component on your device (p. 44) in Getting started with AWS IoT Greengrass V2 (p. 32)
Note
When you use docker exec to run commands inside the Docker container, those commands are not logged in the Docker logs. To log your commands in the Docker logs, attach an
interactive shell to the Docker container. For more information, see Attach an interactive shell to the Docker container (p. 165).
The AWS IoT Greengrass Core log file is called greengrass.log and is located in /greengrass/
v2/logs. Component log files are also located in the same directory. To copy Greengrass logs to a temporary directory on the host, run the following command:
docker cp container-id:/greengrass/v2/logs /tmp/logs
If you want to persist logs after a container exits or has been removed, we recommend that you bind-mount only the /greengrass/v2/logs directory to the temporary logs directory on the host instead of mounting the entire Greengrass directory. For more information, see Persist Greengrass logs outside of the Docker container (p. 164).
To stop a running AWS IoT Greengrass Docker container, run docker stop or docker-compose -f docker-compose.yml stop. This action sends SIGTERM to the Greengrass process and shuts down
Run AWS IoT Greengrass in Docker with manual provisioning
all associated processes that were started in the container. The Docker container is initialized with the docker-init executable as process PID 1, which helps in removing any leftover zombie processes. For more information, see the Docker documentation.
For information about troubleshooting issues with running AWS IoT Greengrass in a Docker container, see Troubleshooting AWS IoT Greengrass in a Docker container (p. 163).