Installing Docker to use with the Amazon SAM CLI - Amazon Serverless Application Model
Installing DockerNext steps
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).

Installing Docker to use with the Amazon SAM CLI

Docker is an application that runs containers on your machine. With Docker, Amazon SAM can provide a local environment similar to Amazon Lambda as a container to build, test, and debug your serverless applications.

Note

Docker is required only for testing your applications locally and for building deployment packages using the --use-container option.

Installing Docker

Follow these instructions to install Docker on your operating system.

Docker is available on many different operating systems, including most modern Linux distributions, such as CentOS, Debian, and Ubuntu. For information about installing Docker on your particular operating system, see Get Docker on the Docker Docs website.

To install Docker on Amazon Linux 2 or Amazon Linux 2023

  1. Update the installed packages and package cache on your instance.

    $ sudo yum update -y

  2. Install the most recent Docker Community Edition package.

    • For Amazon Linux 2, run the following:

      $ sudo amazon-linux-extras install docker

    • For Amazon Linux 2023, run the following:

      $ sudo yum install -y docker

  3. Start the Docker service.

    $ sudo service docker start

  4. Add the ec2-user to the docker group so that you can run Docker commands without using sudo.

    $ sudo usermod -a -G docker ec2-user

  5. Pick up the new docker group permissions by logging out and logging back in again. To do this, close your current SSH terminal window and reconnect to your instance in a new one. Your new SSH session should have the appropriate docker group permissions.

  6. Verify that the ec2-user can run Docker commands without using sudo.

    $ docker ps

    You should see the following output, confirming that Docker is installed and running:

     CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
Note

On Linux, to build and run Lambda functions with a different instruction set architecture than your host machine, there are additional steps to configure Docker. For example, to run arm64 functions on an x86_64 machine, you can run the following command to configure the Docker daemon: docker run --rm --privileged multiarch/qemu-user-static --reset -p yes.

If you run into issues installing Docker, see Installation errors. Or, see the Troubleshooting section of Post-installation steps for Linux on the Docker Docs website.

Note

Docker Desktop is officially supported, but starting with Amazon SAM CLI version 1.47.0, you can use alternatives as long as they use the Docker runtime.

  1. Install Docker

    The Amazon SAM CLI supports Docker running on macOS Sierra 10.12 or later. For how to install Docker, see Install Docker Desktop for Mac on the Docker Docs website.

  2. Configure your shared drives

    The Amazon SAM CLI requires that the project directory, or any parent directory, is listed in a shared drive. This may require file sharing. For more information, see the Volume mounting requires file sharing troubleshooting topic at Docker docs.

  3. Verify the installation

    After Docker is installed, verify that it's working. Also confirm that you can run Docker commands from the command line (for example, docker ps). You don't need to install, fetch, or pull any containers—the Amazon SAM CLI does this automatically as required.

If you run into issues installing Docker, for more troubleshooting tips, see the Troubleshoot and diagnose section of the Docker Docs website.

Note

Amazon SAM officially supports Docker Desktop. However, starting with Amazon SAM CLI version 1.47.0, you can use alternatives as long as they use the Docker runtime.

  1. Install Docker.

    Docker Desktop supports the most recent Windows operating system. For legacy versions of Windows, the Docker Toolbox is available. Choose your version of Windows for the correct Docker installation steps:

  2. Configure your shared drives.

    The Amazon SAM CLI requires that the project directory, or any parent directory, is listed in a shared drive. In some cases, you must share your drive for Docker to function properly.

  3. Verify the installation.

    After Docker is installed, verify that it's working. Also confirm that you can run Docker commands from the command line (for example, docker ps). You don't need to install, fetch, or pull any containers—the Amazon SAM CLI does this automatically as required.

If you run into issues installing Docker, for more troubleshooting tips, see the Troubleshoot and diagnose section of the Docker Docs website.

Next steps

For how to install the Amazon SAM CLI, see Installing the Amazon SAM CLI.