Amazon EC2 Container Service
Developer Guide (API Version 2014-11-13)

Docker Basics

Docker is a technology that allows you to build, run, test, and deploy distributed applications that are based on Linux containers. Amazon ECS uses Docker images in task definitions to launch containers on EC2 instances in your clusters. For Amazon ECS product details, featured customer case studies, and FAQs, see the Amazon EC2 Container Service product detail pages.

The documentation in this guide assumes that readers possess a basic understanding of what Docker is and how it works. For more information about Docker, see What is Docker? and the Docker User Guide.

If you'd like to try out Docker before you install it, go to the interactive tutorial on the Docker website.

Installing Docker

Docker is available on many different operating systems, including most modern Linux distributions, like Ubuntu, and even Mac OSX and Windows. For more information about how to install Docker on your particular operating system, go to the Docker installation guide.

You don't even need a local development system to use Docker. If you are using Amazon EC2 already, you can launch an Amazon Linux instance and install Docker to get started.

To install Docker on an Amazon Linux instance

  1. Launch an instance with the Amazon Linux AMI. For more information, see Launching an Instance in the Amazon EC2 User Guide for Linux Instances.

  2. Connect to your instance. For more information, see Connect to Your Linux Instance in the Amazon EC2 User Guide for Linux Instances.

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

    [ec2-user ~]$ sudo yum update -y
  4. Install Docker.

    [ec2-user ~]$ sudo yum install -y docker
  5. Start the Docker service.

    [ec2-user ~]$ sudo service docker start
    Starting cgconfig service:                                 [  OK  ]
    Starting docker:	                                   [  OK  ]
  6. Add the ec2-user to the docker group so you can execute Docker commands without using sudo.

    [ec2-user ~]$ sudo usermod -a -G docker ec2-user
  7. Log out and log back in again to pick up the new docker group permissions.

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

    [ec2-user ~]$ docker info
    Containers: 2
    Images: 24
    Storage Driver: devicemapper
     Pool Name: docker-202:1-263460-pool
     Pool Blocksize: 65.54 kB
     Data file: /var/lib/docker/devicemapper/devicemapper/data
     Metadata file: /var/lib/docker/devicemapper/devicemapper/metadata
     Data Space Used: 702.3 MB
     Data Space Total: 107.4 GB
     Metadata Space Used: 1.864 MB
     Metadata Space Total: 2.147 GB
     Library Version: 1.02.89-RHEL6 (2014-09-01)
    Execution Driver: native-0.2
    Kernel Version: 3.14.27-25.47.amzn1.x86_64
    Operating System: Amazon Linux AMI 2014.09

(Optional) Sign up for a Docker Hub Account

Docker uses images that are stored in repositories to launch containers with. The most common Docker image repository (and the default repository for the Docker daemon) is Docker Hub. Although you don't need a Docker Hub account to use Amazon ECS or Docker, having a Docker Hub account gives you the freedom to store your modified Docker images so you can use them in your ECS task definitions.

For more information about Docker Hub, and to sign up for an account, go to

Docker Hub offers public and private registries. You can create a private registry on Docker Hub and configure Private Registry Authentication on your ECS container instances to use your private images in task definitions.

(Optional) Amazon EC2 Container Registry

Another registry option is Amazon EC2 Container Registry (Amazon ECR). Amazon ECR is a managed AWS Docker registry service. Customers can use the familiar Docker CLI to push, pull, and manage images. For Amazon ECR product details, featured customer case studies, and FAQs, see the Amazon EC2 Container Registry product detail pages. To finish this walkthrough using Amazon ECR, see Create a Docker Image in the Amazon EC2 Container Registry User Guide.

Create a Docker Image and Upload it to Docker Hub

Amazon ECS task definitions use Docker images to launch containers on the container instances in your clusters. In this section, you create a Docker image of a simple PHP web application, and test it on your local system or EC2 instance, and then push the image to your Docker Hub registry so you can use it in an ECS task definition.

To create a Docker image of a PHP web application

  1. Install git and use it to clone the simple PHP application from your GitHub repository onto your system.

    1. Install git.

      [ec2-user ~]$ sudo yum install -y git
    2. Clone the simple PHP application onto your system.

      [ec2-user ~]$ git clone
  2. Change directories to the ecs-demo-php-simple-app folder.

    [ec2-user ~]$ cd ecs-demo-php-simple-app
  3. Examine the Dockerfile in this folder. A Dockerfile is a manifest that describes the base image to use for your Docker image and what you want installed and running on it. For more information about Dockerfiles, go to the Dockerfile Reference.

    [ec2-user ecs-demo-php-simple-app]$ cat Dockerfile
    FROM ubuntu:12.04
    # Install dependencies
    RUN apt-get update -y
    RUN apt-get install -y git curl apache2 php5 libapache2-mod-php5 php5-mcrypt php5-mysql
    # Install app
    RUN rm -rf /var/www/*
    ADD src /var/www
    # Configure apache
    RUN a2enmod rewrite
    RUN chown -R www-data:www-data /var/www
    ENV APACHE_RUN_USER www-data
    ENV APACHE_LOG_DIR /var/log/apache2
    EXPOSE 80
    CMD ["/usr/sbin/apache2", "-D",  "FOREGROUND"]

    This Dockerfile uses the Ubuntu 12.04 image. The RUN instructions update the package caches, install some software packages for the web server and PHP support, and then add your PHP application to the web server's document root. The EXPOSE instruction exposes port 80 on the container, and the CMD instruction starts the web server.

  4. Build the Docker image from your Dockerfile. Substitute my-dockerhub-username with your Docker Hub user name.

    [ec2-user ecs-demo-php-simple-app]$ docker build -t my-dockerhub-username/amazon-ecs-sample .
  5. Run docker images to verify that the image was created correctly and that the image name contains a repository that you can push to (in this example, your Docker Hub user name).

    [ec2-user ecs-demo-php-simple-app]$ docker images
    REPOSITORY                                TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
    my-dockerhub-username/amazon-ecs-sample   latest              43c52559a0a1        12 minutes ago      258.1 MB
    ubuntu                                    12.04               78cef618c77e        3 weeks ago         133.7 MB
  6. Run the newly built image. The -p 80:80 option maps the exposed port 80 on the container to port 80 on the host system. For more information about docker run, go to the Docker run reference.

    [ec2-user ecs-demo-php-simple-app]$ docker run -p 80:80 my-dockerhub-username/amazon-ecs-sample
    apache2: Could not reliably determine the server's fully qualified domain name, using for ServerName


    Output from the Apache web server is displayed in the terminal window. You can ignore the "Could not reliably determine the server's fully qualified domain name" message.

  7. Open a browser and point to the server that is running Docker and hosting your container.

    • If you are using an EC2 instance, this is the Public DNS value for the server, which is the same address you use to connect to the instance with SSH. Make sure that the security group for your instance allows inbound traffic on port 80.

    • If you are running Docker locally on a Linux computer, point your browser to http://localhost/.

    • If you are using boot2docker on a Windows or Mac computer, find the IP address of the VirtualBox VM that is hosting Docker with the boot2docker ip command.

      $ boot2docker ip
    • If you are using docker-machine on a Windows or Mac computer, find the IP address of the VirtualBox VM that is hosting Docker with the docker-machine ip command, substituting machine-name with the name of the docker machine you are using.

      $ docker-machine ip machine-name

    You should see a web page running the simple PHP app.

    Simple PHP app
  8. Stop the Docker container by typing Ctrl+c.

Next Steps

After the image push is finished, you can use the my-dockerhub-username/amazon-ecs-sample image in your Amazon ECS task definitions, which you can use to run tasks with.

To register a task definition with the amazon-ecs-sample image

  1. Examine the simple-app-task-def.json file in the ecs-demo-php-simple-app folder.

        "family": "console-sample-app",
        "volumes": [
                "name": "my-vol",
                "host": {}
        "containerDefinitions": [
                "environment": [],
                "name": "simple-app",
                "image": "amazon/amazon-ecs-sample",
                "cpu": 10,
                "memory": 500,
                "portMappings": [
                        "containerPort": 80,
                        "hostPort": 80
                "mountPoints": [
                        "sourceVolume": "my-vol",
                        "containerPath": "/var/www/my-vol"
                "entryPoint": [
                "essential": true
                "name": "busybox",
                "image": "busybox",
                "cpu": 10,
                "memory": 500,
                "volumesFrom": [
                  "sourceContainer": "simple-app"
                "entryPoint": [
                "command": [
                    "/bin/sh -c \"while true; do /bin/date > /var/www/my-vol/date; sleep 1; done\""
                "essential": false

    This task definition JSON file specifies two containers, one of which uses the amazon-ecs-sample image. By default, this image is pulled from the Amazon Docker Hub repository, but you can change the amazon repository defined above to your own repository if you want to use the my-dockerhub-username/amazon-ecs-sample image you pushed earlier.

  2. Register a task definition with the simple-app-task-def.json file.

    [ec2-user ecs-demo-php-simple-app]$ aws ecs register-task-definition --cli-input-json file://simple-app-task-def.json

    The task definition is registered in the console-sample-app family as defined in the JSON file.

To run a task with the console-sample-app task definition


Before you can run tasks in Amazon ECS, you need to launch container instances into your cluster. For more information about how to set up and launch container instances, see Setting Up with Amazon ECS and Getting Started with Amazon ECS.

  • Use the following AWS CLI command to run a task with the console-sample-app task definition.

    [ec2-user ecs-demo-php-simple-app]$ aws ecs run-task --task-definition console-sample-app