# Migrating to Elastic Beanstalk Docker running on Amazon Linux 2 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 your Elastic Beanstalk application from ECS managed Multi-container Docker on AL1 to ECS on Amazon Linux 2023](migrate-to-ec2-AL2-platform.md).
## Legacy Migration from Multi-container Docker on Amazon Linux to the Docker Amazon Linux 2 platform branch
You can migrate your applications running on the [Multi-container Docker platform on Amazon Linux AMI](create_deploy_docker_ecs.md) 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](https://docs.docker.com/compose/) and [Install Docker Compose](https://docs.docker.com/compose/install/).
### 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](https://docs.docker.com/compose/compose-file/). For more information on the `Dockerrun.aws.json v2` file, see [`Dockerrun.aws.json` v2](create_deploy_docker_v2config.md#create_deploy_docker_v2config_dockerrun).
| **`docker-compose.yml`** | **`Dockerrun.aws.json v2`** |
| --- | --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/docker-multicontainer-migration.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/docker-multicontainer-migration.html) |
| 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](create_deploy_docker.container.console.md#docker-env-cfg.env-variables). | 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/` (or `${EB_LOG_BASE_DIR}/`). For more information see [Docker container customized logging with Docker Compose](create_deploy_docker.container.console.md#docker-env-cfg.dc-customized-logging). | For each container, Elastic Beanstalk creates a log directory called `/var/log/containers/`. For more information see `mountPoints` field in [Container definition format](create_deploy_docker_v2config.md#create_deploy_docker_v2config_dockerrun_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](#docker-multicontainer-migration.files).
1. 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
```
1. Use the **eb init** command to configure your local directory for deployment to Elastic Beanstalk.
```
~/myApplication$ eb init -p docker application-name
```
1. Use the **eb create** command to create an environment and deploy your Docker image.
```
~/myApplication$ eb create environment-name
```
1. 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
```
1. You can display the status of your newly created environment using the **eb status** command.
```
~/myApplication$ eb status environment-name
```