(Legacy) Migrating to the Docker running on Amazon Linux 2 platform branch from Multi-container Docker running on Amazon Linux - AWS Elastic Beanstalk

(Legacy) Migrating to the Docker running on Amazon Linux 2 platform branch from Multi-container Docker running on Amazon Linux

Prior to the release of the ECS Running on 64bit Amazon Linux 2 platform branch, Elastic Beanstalk offered an alternate migration path to Amazon Linux 2 for customers with environments based on the Multi-container Docker running on 64bit Amazon Linux platform branch. This topic describes that migration path, and remains in this document as a reference for any customers that completed that migration path.

We now recommend that customers with environments based on the Multi-container Docker running on 64bit Amazon Linux platform branch migrate to the ECS Running on 64bit Amazon Linux 2 platform branch. Unlike the alternate migration path, this approach continues to use Amazon ECS to coordinate container deployments to ECS managed Docker environments. This aspect allows a more straightforward approach. No changes to the source code are required, and the same Dockerrun.aws.json v2 is supported. For more information, see Migrating Multi-container Docker running on Amazon Linux to ECS on Amazon Linux 2023.

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.

Docker Compose is tool for defining and running multi-container Docker applications. 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

The Docker Amazon Linux 2 platform and Multi-container Docker Amazon Linux AMI platform implement environment properties differently. These two platforms also have different log directories that Elastic Beanstalk creates for each of their containers. After you migrate from the Amazon Linux AMI Multi-container Docker platform, you will need to be aware of these different implementations for your new Amazon Linux 2 Docker platform environment.

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

Environment properties

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.

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.

Log directories

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).

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

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