Migrating to the Docker Amazon Linux 2 Platform - AWS Elastic Beanstalk
The docker-compose.yml fileAdditional Migration ConsiderationsMigration Steps

Migrating to the Docker Amazon Linux 2 Platform

Important

Amazon Linux 2 platform versions are fundamentally different than Amazon Linux AMI platform versions (preceding Amazon Linux 2). These different platform generations are incompatible in several ways. If you are migrating to an Amazon Linux 2 platform version, be sure to read the information in Migrating your Elastic Beanstalk Linux application to Amazon Linux 2.

You can migrate your applications running on the Multi-container Docker platform on Amazon Linux AMI to the Amazon Linux 2 Docker platform. The Multi-container Docker platform on Amazon Linux AMI requires that you specify prebuilt application images to run as containers. After migrating, you will no longer have this limitation, because the Amazon Linux 2 Docker platform also allows Elastic Beanstalk to build your container images during deployment.

Your applications will continue to run in multi-container environments with the added benefits from the Docker Compose tool. To learn more about Docker Compose and how to install it, see the Docker sites Overview of Docker Compose and Install Docker Compose.

The docker-compose.yml file

The Docker Compose tool uses the docker-compose.yml file for configuration of your application services. This file replaces your Dockerrun.aws.json v2 file in your application project directory and application source bundle. You create the docker-compose.yml file manually, and will find it helpful to reference your Dockerrun.aws.json v2 file for most of the parameter values.

Below is an example of a docker-compose.yml file and the corresponding Dockerrun.aws.json v2 file for the same application. For more information on the docker-compose.yml file, see Compose file reference. For more information on the Dockerrun.aws.json v2 file, see Dockerrun.aws.json v2.

docker-compose.yml Dockerrun.aws.json v2 
version: '2.4'
services:
  php-app:
    image: "php:fpm"
    volumes:
      - "./php-app:/var/www/html:ro"
      - "${EB_LOG_BASE_DIR}/php-app:/var/log/sample-app"
    mem_limit: 128m
    environment:
      Container: PHP
  nginx-proxy:
    image: "nginx"
    ports:
      - "80:80"
    volumes:
      - "./php-app:/var/www/html:ro"
      - "./proxy/conf.d:/etc/nginx/conf.d:ro"
      - "${EB_LOG_BASE_DIR}/nginx-proxy:/var/log/nginx"
    mem_limit: 128m
    links:
      - php-app
 
{
  "AWSEBDockerrunVersion": 2,
  "volumes": [
    {
      "name": "php-app",
      "host": {
        "sourcePath": "/var/app/current/php-app"
      }
    },
    {
      "name": "nginx-proxy-conf",
      "host": {
        "sourcePath": "/var/app/current/proxy/conf.d"
      }
    }
  ],
  "containerDefinitions": [
    {
      "name": "php-app",
      "image": "php:fpm",
      "environment": [
        {
          "name": "Container",
          "value": "PHP"
        }
      ],
      "essential": true,
      "memory": 128,
      "mountPoints": [
        {
          "sourceVolume": "php-app",
          "containerPath": "/var/www/html",
          "readOnly": true
        }
      ]
    },
    {
      "name": "nginx-proxy",
      "image": "nginx",
      "essential": true,
      "memory": 128,
      "portMappings": [
        {
          "hostPort": 80,
          "containerPort": 80
        }
      ],
      "links": [
        "php-app"
      ],
      "mountPoints": [
        {
          "sourceVolume": "php-app",
          "containerPath": "/var/www/html",
          "readOnly": true
        },
        {
          "sourceVolume": "nginx-proxy-conf",
          "containerPath": "/etc/nginx/conf.d",
          "readOnly": true
        },
        {
          "sourceVolume": "awseb-logs-nginx-proxy",
          "containerPath": "/var/log/nginx"
        }
      ]
    }
  ]
}

Additional Migration Considerations

Area Multi-container Docker platform on Amazon Linux AMI Docker platform on Amazon Linux 2 with Docker Compose

Environment properties

Elastic Beanstalk can directly pass environment properties to the container. Your code running in the container can access these properties as environment variables without any additional configuration.

In order for your containers to access environment properties you must add a reference to the .env file in the docker-compose.yml file. Elastic Beanstalk generates the .env file, listing each of the properties as environment variables. For more information see Referencing environment variables in containers.

Log directories

For each container, Elastic Beanstalk creates a log directory called /var/log/containers/<containername>. For more information see mountPoints field in Container definition format.

For each container Elastic Beanstalk creates a log directory called /var/log/eb-docker/containers/<service name> (or ${EB_LOG_BASE_DIR}/<service name>). For more information see Docker container customized logging (Docker Compose).

Migration Steps

To migrate to the Amazon Linux 2 Docker platform

  1. Create the docker-compose.yml file for your application, based on its existing Dockerrun.aws.json v2 file. For more information see the above section The docker-compose.yml file.

  2. In your application project folder's root directory, replace the Dockerrun.aws.json v2 file with the docker-compose.yml you just created.

    Your directory structure should be as follows.

    ~/myApplication
|-- docker-compose.yml
|-- .ebextensions
|-- php-app
|-- proxy

  3. Use the eb init command to configure your local directory for deployment to Elastic Beanstalk. 

    ~/myApplication$ eb init -p docker application-name

  4. Use the eb create command to create an environment and deploy your Docker image. 

    ~/myApplication$ eb create environment-name

  5. If your app is a web application, after your environment launches, use the eb open command to view it in a web browser. 

    ~/myApplication$ eb open environment-name

  6. You can display the status of your newly created environment using the eb status command. 

    ~/myApplication$ eb status environment-name