How can I troubleshoot a deployment failure for an AWS IoT Greengrass component that runs a Docker container?

Short description

When an AWS IoT Greengrass component that runs a Docker container fails to deploy, the error is typically caused by a permissions issue.

The following is an example error message for a component deployment failure:

com.example.RaspberryDockerComponent: stderr. permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/images/load?quiet=1": dial unix /var/run/docker.sock: connect: permission denied. {scriptName=services.com.example.RaspberryDockerComponent.lifecycle.Install.Script, serviceName=com.example.RaspberryDockerComponent, currentState=NEW}

Resolution

To successfully deploy an AWS IoT Greengrass component that runs a Docker container, change one of the following permissions:

• (Best practice) Configure the Docker container to run for non-root or non-administrator users.
• Grant root or administrator permissions to the user who deploys the component.

When a user gets a permission denied error, an administrator user must add the user to the Docker group. As a member of the Docker group, the user can run commands without administrator privileges.

To add user permissions, complete the following steps:

1. To add ggc_user to the Docker group, run the following command:

   sudo usermod -aG docker ggc_user

   Note: In your command, replace ggc_user with your non-root user.

2. To restart AWS IoT Greengrass to apply the user permissions updates, run the following command:

   systemctl restart greengrass

3. Redeploy the component, and then verify that the user can run commands.

Related information

Run a Docker container