AWS Elastic Beanstalk
Developer Guide (API Version 2010-12-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Dockerfile and Dockerrun.aws.json

This section describes how to prepare your Docker image and container for uploading to AWS Elastic Beanstalk. Any web application that you deploy to AWS Elastic Beanstalk from a Docker container must include at least one of two manifest files, either a Dockerfile or a Dockerrun.aws.json file. You can deploy your web application from a Docker container to AWS Elastic Beanstalk by doing one of the following:

  • Create a Dockerfile to deploy a Docker container to AWS Elastic Beanstalk.

  • Create a Dockerrun.aws.json file to deploy a Docker container from an existing Docker image to AWS Elastic Beanstalk.

  • Create a .zip file containing your application files, any application file dependencies, the Dockerfile, and the Dockerrun.aws.json file.

    Note

    If you use only a Dockerfile or only a Dockerrun.aws.json file to deploy your application, you do not need to compress the file into a .zip file.

Docker uses a Dockerfile to create a Docker image that contains your source bundle. A Docker image is the template from which you create a Docker container. Dockerfile is a plain text file that contains instructions that AWS Elastic Beanstalk uses to build a customized Docker image on each Amazon EC2 instance in your AWS Elastic Beanstalk environment. Create the Dockerfile when you do not already have an existing image hosted in a repository. Include the following instructions in the Dockerfile:

  • FROM – (required as the first instruction in the file) Specifies the base image from which to build the Docker container and against which AWS Elastic Beanstalk runs subsequent Dockerfile instructions.

    The image can be hosted in a public repository, a private repository hosted by a third-party registry, or a repository that you run on EC2.

  • EXPOSE – (required) Lists the ports to expose on the Docker container. AWS Elastic Beanstalk uses the port value to connect the Docker container to the reverse proxy running on the host.

    You can specify multiple container ports, but AWS Elastic Beanstalk uses only the first one to connect your container to the host's reverse proxy and route requests from the public Internet.

  • ENTRYPOINT – (not required if you specify the CMD instruction) Specifies the command to run the image. The command should be expressed as a JSON array with the full path to the executable.

  • CMD – (not required if you specify the ENTRYPOINT instruction) Specifies the command to run the image. The command should be expressed as a JSON array with the full path to the executable.

  • RUN – Specifies one or more commands that install packages and configure your web application inside the image.

    If you include RUN instructions in the Dockerfile, compress the file and the context used by RUN instructions in the Dockerfile into a .zip file. Compress files at the top level of the directory.

Note

To use a private repository hosted by a third-party registry, you must provide a JSON file called .dockercfg with information required to authenticate with the repository. Declare the .dockercfg file in the Dockerrun.aws.json file. Make sure that the .dockercfg file contains a valid Amazon S3 bucket and Amazon EC2 key pair. Grant permissions for the action s3:GetObject to the IAM role in the instance profile. For an example policy, see Using IAM Roles with AWS Elastic Beanstalk. For more information about the .dockercfg file, see the Authentication File section of Working with a Docker Repository on the Docker website.

The following snippet is an example of the Dockerfile. When you follow the instructions in Deploying an Application from a Docker Container to AWS Elastic Beanstalk Using the Elastic Beanstalk Console, you can upload this Dockerfile as written. AWS Elastic Beanstalk runs the game 2048 when you use this Dockerfile.

FROM ubuntu:12.04

RUN apt-get update
RUN apt-get install -y nginx zip curl

RUN echo "daemon off;" >> /etc/nginx/nginx.conf
RUN curl -o /usr/share/nginx/www/master.zip -L https://codeload.github.com/gabrielecirulli/2048/zip/master
RUN cd /usr/share/nginx/www/ && unzip master.zip && mv 2048-master/* . && rm -rf 2048-master master.zip

EXPOSE 80

CMD ["/usr/sbin/nginx", "-c", "/etc/nginx/nginx.conf"]

For more information about instructions you can include in the Dockerfile, go to Dockerfile Reference on the Docker website.

A Dockerrun.aws.json file describes how to deploy a Docker container as an AWS Elastic Beanstalk application. This JSON file is specific to AWS Elastic Beanstalk. You can provide AWS Elastic Beanstalk with only the Dockerrun.aws.json file or in addition to the Dockerfile in a .zip file. When you provide both files, the Dockerfile builds the Docker image and the Dockerrun.aws.json file provides additional information for deployment as described later in this section. When you provide both the Dockerfile and the Dockerrun.aws.json file, do not include information about the image in the Dockerrun.aws.json file. AWS Elastic Beanstalk uses the image specified in the Dockerfile and ignores it in the Dockerrun.aws.json file.

Valid keys and values for the Dockerrun.aws.json file include the following:

  • AWSEBDockerrunVersion – (required) Specifies the version number as the value "1".

  • Authentication – (required only for private repositories) Specifies the Amazon S3 object storing the .dockercfg file.

  • Image – Specifies the Docker base image on an existing Docker repository from which you're building a Docker container. Specify the value of the Name key in the format <repository name>/<image name>. When you specify an image in the Dockerrun.aws.json file, each instance in your AWS Elastic Beanstalk environment will run docker pull on that image and run it. Optionally include the Update key. The default value is "true" and instructs AWS Elastic Beanstalk to check the repository, pull any updates to the image, and overwrite any cached images.

    Do not specify the Image key in the Dockerrun.aws.json file when you deploy with a .zip file that includes a Dockerfile. The Dockerfile contains instructions to build a Docker image (from which you build the Docker container).

  • Ports – (required when you specify the Image key) Lists the ports to expose on the Docker container. AWS Elastic Beanstalk uses ContainerPort value to connect the Docker container to the reverse proxy running on the host.

    You can specify multiple container ports, but AWS Elastic Beanstalk uses only the first one to connect your container to the host's reverse proxy and route requests from the public Internet.

  • Volumes – Maps volumes from an EC2 instance to your Docker container. Specify one or more arrays of volumes to map.

  • Logging – Maps the log directory inside the container.

    Configure AWS Elastic Beanstalk to publish log files for the Docker container or to view snapshot logs. For more information, see Working with Logs.

The following snippet is an example that illustrates the syntax of the Dockerrun.aws.json file.

{
  "AWSEBDockerrunVersion": "1",
  "Authentication": {
    "Bucket": "my-bucket",
    "Key": "mydockercfg"
  },
  "Image": {
    "Name": "janedoe/image",
    "Update": "true"
  },
  "Ports": [
    {
      "ContainerPort": "1234"
    }
  ],
  "Volumes": [
    {
      "HostDirectory": "/var/app/mydb",
      "ContainerDirectory": "/etc/mysql"
    }
  ],
  "Logging": "/var/log/nginx"
}