# Using the Elastic Beanstalk Docker platform branch This section describes how to prepare your Docker image for launch with the either of the Elastic Beanstalk platform branches *Docker running AL2 or AL2023*. Follow the steps in [QuickStart for Docker](docker-quickstart.md) to create a Docker "Hello World" application and deploy it to an Elastic Beanstalk environment using the EB CLI. **Topics** + [ # QuickStart: Deploy a Docker application to Elastic Beanstalk ](docker-quickstart.md) + [ # QuickStart: Deploy a Docker Compose application to Elastic Beanstalk ](docker-compose-quickstart.md) + [ # Preparing your Docker image for deployment to Elastic Beanstalk ](single-container-docker-configuration.md) # QuickStart: Deploy a Docker application to Elastic Beanstalk This QuickStart tutorial walks you through the process of creating a Docker application and deploying it to an AWS Elastic Beanstalk environment. **Not for production use** Examples are intended for demonstration only. Do not use example applications in production. **Topics** + [ ## Your AWS account ](#docker-quickstart-aws-account) + [ ## Prerequisites ](#docker-quickstart-prereq) + [ ## Step 1: Create a Docker application and container ](#docker-quickstart-create-app) + [ ## Step 2: Run your application locally ](#docker-quickstart-run-local) + [ ## Step 3: Deploy your Docker application with the EB CLI ](#docker-quickstart-deploy) + [ ## Step 4: Run your application on Elastic Beanstalk ](#docker-quickstart-run-eb-ap) + [ ## Step 5: Clean up ](#go-tutorial-cleanup) + [ ## AWS resources for your application ](#docker-quickstart-eb-resources) + [ ## Next steps ](#docker-quickstart-next-steps) + [ ## Deploy with the Elastic Beanstalk console ](#docker-quickstart-console) ## Your AWS account If you're not already an AWS customer, you need to create an AWS account. Signing up enables you to access Elastic Beanstalk and other AWS services that you need. If you already have an AWS account, you can move on to [Prerequisites](#docker-quickstart-prereq). ### Create an AWS account #### Sign up for an AWS account If you do not have an AWS account, complete the following steps to create one. **To sign up for an AWS account** 1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup). 1. Follow the online instructions. Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad. When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks). AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**. #### Create a user with administrative access After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks. **Secure your AWS account root user** 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*. 1. Turn on multi-factor authentication (MFA) for your root user. For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*. **Create a user with administrative access** 1. Enable IAM Identity Center. For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*. 1. In IAM Identity Center, grant administrative access to a user. For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*. **Sign in as the user with administrative access** + To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user. For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*. **Assign access to additional users** 1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions. For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*. 1. Assign users to a group, and then assign single sign-on access to the group. For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*. ## Prerequisites To follow the procedures in this guide, you will need a command line terminal or shell to run commands. Commands are shown in listings preceded by a prompt symbol (\$1) and the name of the current directory, when appropriate. ``` ~/eb-project$ this is a command this is output ``` On Linux and macOS, you can use your preferred shell and package manager. On Windows you can [install the Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) to get a Windows-integrated version of Ubuntu and Bash. ### EB CLI This tutorial uses the Elastic Beanstalk Command Line Interface (EB CLI). For details on installing and configuring the EB CLI, see [Install EB CLI with setup script (recommended)](eb-cli3.md#eb-cli3-install) and [Configure the EB CLI](eb-cli3-configuration.md). ### Docker To follow this tutorial, you'll need a working local installation of Docker. For more information, see [Get Docker](https://docs.docker.com/get-docker/) on the Docker documentation website. Verify the Docker daemon is up an running by running the following command. ``` ~$ docker info ``` ## Step 1: Create a Docker application and container For this example, we create a Docker image of the sample Flask application that's also referenced in [Deploying a Flask application to Elastic Beanstalk](create-deploy-python-flask.md). The application consists of two files: + `app.py`— the Python file that contains the code that will execute in the container. + `Dockerfile`— the Dockerfile to build your image. Place both files at the root of a directory. ``` ~/eb-docker-flask/ |-- Dockerfile |-- app.py ``` Add the following contents to your `Dockerfile`. **Example `~/eb-docker-flask/Dockerfile`** ``` FROM public.ecr.aws/docker/library/python:3.12 COPY . /app WORKDIR /app RUN pip install Flask==3.1.1 EXPOSE 5000 CMD [ "python3", "-m" , "flask", "run", "--host=0.0.0.0"] ``` Add the following contents to your `app.py` file. **Example `~/eb-docker-flask/app.py`** ``` from flask import Flask app = Flask(__name__) @app.route('/') def hello_world(): return 'Hello Elastic Beanstalk! This is a Docker application' ``` Use the [docker build](https://docs.docker.com/reference/cli/docker/image/build/) command to build your container image locally, tagging the image with `eb-docker-flask`. The period (`.`) at the end of the command specificies that path is a local directory. ``` ~/eb-docker-flask$ docker build -t eb-docker-flask . ``` ## Step 2: Run your application locally Run your container with the [docker run](https://docs.docker.com/reference/cli/docker/container/run/) command. The command will print the ID of the running container. The **-d** option runs docker in background mode. The **-p** option exposes your application at port 5000. Elastic Beanstalk serves traffic to port 5000 on the Docker platform by default. ``` ~/eb-docker-flask$ docker run -dp 127.0.0.1:5000:5000 eb-docker-flask ``` Navigate to `http://127.0.0.1:5000/ `in your browser. You should see the text "Hello Elastic Beanstalk\$1 This is a Docker application". Run the [docker kill](https://docs.docker.com/reference/cli/docker/container/kill/) command to terminate the container. ``` ~/eb-docker-flask$ docker kill container-id ``` ## Step 3: Deploy your Docker application with the EB CLI Run the following commands to create an Elastic Beanstalk environment for this application. **To create an environment and deploy your Docker application** 1. Initialize your EB CLI repository with the **eb init** command. ``` ~/eb-docker-flask$ eb init -p docker docker-tutorial --region us-east-2 Application docker-tutorial has been created. ``` This command creates an application named `docker-tutorial` and configures your local repository to create environments with the latest Docker platform version. 1. (Optional) Run **eb init** again to configure a default key pair so that you can use SSH to connect to the EC2 instance running your application. ``` ~/eb-docker-flask$ eb init Do you want to set up SSH for your instances? (y/n): y Select a keypair. 1) my-keypair 2) [ Create new KeyPair ] ``` Select a key pair if you have one already, or follow the prompts to create one. If you don't see the prompt or need to change your settings later, run **eb init -i**. 1. Create an environment and deploy your application to it with **eb create**. Elastic Beanstalk automatically builds a zip file for your application and starts it on port 5000. ``` ~/eb-docker-flask$ eb create docker-tutorial ``` It takes about five minutes for Elastic Beanstalk to create your environment. ## Step 4: Run your application on Elastic Beanstalk When the process to create your environment completes, open your website with **eb open**. ``` ~/eb-docker-flask$ eb open ``` Congratulations\$1 You've deployed a Docker application with Elastic Beanstalk\$1 This opens a browser window using the domain name created for your application. ## Step 5: Clean up You can terminate your environment when you finish working with your application. Elastic Beanstalk terminates all AWS resources associated with your environment. To terminate your Elastic Beanstalk environment with the EB CLI run the following command. ``` ~/eb-docker-flask$ eb terminate ``` ## AWS resources for your application You just created a single instance application. It serves as a straightforward sample application with a single EC2 instance, so it doesn't require load balancing or auto scaling. For single instance applications Elastic Beanstalk creates the following AWS resources: + **EC2 instance** – An Amazon EC2 virtual machine configured to run web apps on the platform you choose. Each platform runs a different set of software, configuration files, and scripts to support a specific language version, framework, web container, or combination thereof. Most platforms use either Apache or nginx as a reverse proxy that processes web traffic in front of your web app, forwards requests to it, serves static assets, and generates access and error logs. + **Instance security group** – An Amazon EC2 security group configured to allow incoming traffic on port 80. This resource lets HTTP traffic from the load balancer reach the EC2 instance running your web app. By default, traffic is not allowed on other ports. + **Amazon S3 bucket** – A storage location for your source code, logs, and other artifacts that are created when you use Elastic Beanstalk. + **Amazon CloudWatch alarms** – Two CloudWatch alarms that monitor the load on the instances in your environment and are triggered if the load is too high or too low. When an alarm is triggered, your Auto Scaling group scales up or down in response. + **CloudFormation stack** – Elastic Beanstalk uses CloudFormation to launch the resources in your environment and propagate configuration changes. The resources are defined in a template that you can view in the [CloudFormation console](https://console.aws.amazon.com/cloudformation). + **Domain name** – A domain name that routes to your web app in the form **subdomain*.*region*.elasticbeanstalk.com*. Elastic Beanstalk manages all of these resources. When you terminate your environment, Elastic Beanstalk terminates all the resources that it contains. ## Next steps After you have an environment running an application, you can deploy a new version of the application or a different application at any time. Deploying a new application version is very quick because it doesn't require provisioning or restarting EC2 instances. You can also explore your new environment using the Elastic Beanstalk console. For detailed steps, see [Explore your environment](GettingStarted.md#GettingStarted.Explore) in the *Getting started* chapter of this guide. After you deploy a sample application or two and are ready to start developing and running Docker applications locally, see [Preparing your Docker image for deployment to Elastic Beanstalk](single-container-docker-configuration.md). ## Deploy with the Elastic Beanstalk console You can also use the Elastic Beanstalk console to launch the sample application. For detailed steps, see [Create an example application](GettingStarted.md#GettingStarted.CreateApp) in the *Getting started* chapter of this guide. # QuickStart: Deploy a Docker Compose application to Elastic Beanstalk This QuickStart tutorial walks you through the process of creating a multi-container Docker Compose application and deploying it to an AWS Elastic Beanstalk environment. You'll create a Flask web application with an nginx reverse proxy to demonstrate how Docker Compose simplifies orchestrating multiple containers. **Not for production use** Examples are intended for demonstration only. Do not use example applications in production. **Topics** + [ ## Your AWS account ](#docker-compose-quickstart-aws-account) + [ ## Prerequisites ](#docker-compose-quickstart-prereq) + [ ## Step 1: Create a Docker Compose application ](#docker-compose-quickstart-create-app) + [ ## Step 2: Run your application locally ](#docker-compose-quickstart-run-local) + [ ## Step 3: Deploy your Docker Compose application with the EB CLI ](#docker-compose-quickstart-deploy) + [ ## Step 4: Test your application on Elastic Beanstalk ](#docker-compose-quickstart-run-eb-ap) + [ ## Step 5: Clean up ](#docker-compose-quickstart-cleanup) + [ ## AWS resources for your application ](#docker-compose-quickstart-eb-resources) + [ ## Next steps ](#docker-compose-quickstart-next-steps) + [ ## Deploy with the Elastic Beanstalk console ](#docker-compose-quickstart-console) ## Your AWS account If you're not already an AWS customer, you need to create an AWS account. Signing up enables you to access Elastic Beanstalk and other AWS services that you need. If you already have an AWS account, you can move on to [Prerequisites](#docker-compose-quickstart-prereq). ### Create an AWS account #### Sign up for an AWS account If you do not have an AWS account, complete the following steps to create one. **To sign up for an AWS account** 1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup). 1. Follow the online instructions. Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad. When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks). AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**. #### Create a user with administrative access After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks. **Secure your AWS account root user** 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*. 1. Turn on multi-factor authentication (MFA) for your root user. For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*. **Create a user with administrative access** 1. Enable IAM Identity Center. For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*. 1. In IAM Identity Center, grant administrative access to a user. For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*. **Sign in as the user with administrative access** + To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user. For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*. **Assign access to additional users** 1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions. For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*. 1. Assign users to a group, and then assign single sign-on access to the group. For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*. ## Prerequisites To follow the procedures in this guide, you will need a command line terminal or shell to run commands. Commands are shown in listings preceded by a prompt symbol (\$1) and the name of the current directory, when appropriate. ``` ~/eb-project$ this is a command this is output ``` On Linux and macOS, you can use your preferred shell and package manager. On Windows you can [install the Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) to get a Windows-integrated version of Ubuntu and Bash. ### EB CLI This tutorial uses the Elastic Beanstalk Command Line Interface (EB CLI). For details on installing and configuring the EB CLI, see [Install EB CLI with setup script (recommended)](eb-cli3.md#eb-cli3-install) and [Configure the EB CLI](eb-cli3-configuration.md). ### Docker and Docker Compose To follow this tutorial, you'll need a working local installation of Docker and Docker Compose. For more information, see [Get Docker](https://docs.docker.com/get-docker/) and [Install Docker Compose](https://docs.docker.com/compose/install/) on the Docker documentation website. Verify that Docker and Docker Compose are installed and running by running the following commands. ``` ~$ docker info ~$ docker compose version ``` ## Step 1: Create a Docker Compose application For this example, we create a multi-container application using Docker Compose that consists of a Flask web application and an nginx reverse proxy. This demonstrates how Docker Compose simplifies orchestrating multiple containers that work together. The application includes health monitoring configuration that allows Elastic Beanstalk to collect detailed application metrics from your nginx proxy. The application consists of the following structure: ``` ~/eb-docker-compose-flask/ |-- docker-compose.yml |-- web/ | |-- Dockerfile | |-- app.py | `-- requirements.txt |-- proxy/ | |-- Dockerfile | `-- nginx.conf `-- .platform/ `-- hooks/ `-- postdeploy/ `-- 01_setup_healthd_permissions.sh ``` Create the directory structure and add the following files: First, create the main `docker-compose.yml` file that defines the services and their relationships. **Example `~/eb-docker-compose-flask/docker-compose.yml`** ``` services: web: build: ./web expose: - "5000" nginx-proxy: build: ./proxy ports: - "80:80" volumes: - "/var/log/nginx:/var/log/nginx" depends_on: - web ``` Create the Flask web application in the `web` directory. Add the following contents to your `app.py` file. **Example `~/eb-docker-compose-flask/web/app.py`** ``` from flask import Flask app = Flask(__name__) @app.route('/') def hello_world(): return 'Hello Elastic Beanstalk! This is a Docker Compose application' ``` Add the following contents to your web service `Dockerfile`. **Example `~/eb-docker-compose-flask/web/Dockerfile`** ``` FROM public.ecr.aws/docker/library/python:3.12 COPY . /app WORKDIR /app RUN pip install Flask==3.1.1 EXPOSE 5000 CMD [ "python3", "-m" , "flask", "run", "--host=0.0.0.0"] ``` Create the nginx reverse proxy in the `proxy` directory. Add the following contents to your `nginx.conf` file. This configuration includes health monitoring setup that allows Elastic Beanstalk to collect detailed application metrics. For more information about customizing health monitoring log formats, see [Enhanced health log format](health-enhanced-serverlogs.md). **Example `~/eb-docker-compose-flask/proxy/nginx.conf`** ``` events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; map $http_upgrade $connection_upgrade { default "upgrade"; } # Health monitoring log format for Elastic Beanstalk log_format healthd '$msec"$uri"$status"$request_time"$upstream_response_time"$http_x_forwarded_for'; upstream flask_app { server web:5000; } server { listen 80 default_server; root /usr/share/nginx/html; # Standard access log access_log /var/log/nginx/access.log; # Health monitoring log for Elastic Beanstalk if ($time_iso8601 ~ "^(\d{4})-(\d{2})-(\d{2})T(\d{2})") { set $year $1; set $month $2; set $day $3; set $hour $4; } access_log /var/log/nginx/healthd/application.log.$year-$month-$day-$hour healthd; location / { proxy_pass http://flask_app; proxy_http_version 1.1; proxy_set_header Connection $connection_upgrade; proxy_set_header Upgrade $http_upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } } ``` Add the following contents to your proxy service `Dockerfile`. **Example `~/eb-docker-compose-flask/proxy/Dockerfile`** ``` FROM public.ecr.aws/nginx/nginx:alpine COPY nginx.conf /etc/nginx/nginx.conf EXPOSE 80 ``` Finally, create a platform hook script to set up the necessary log directories and permissions for health monitoring. Platform hooks allow you to run custom scripts during the deployment process. For more information about platform hooks, see [Platform hooks](platforms-linux-extend.hooks.md). **Example `~/eb-docker-compose-flask/.platform/hooks/postdeploy/01_setup_healthd_permissions.sh`** ``` #!/bin/bash set -ex NGINX_CONTAINER=$(docker ps --filter "name=nginx-proxy" -q) if [ -z "$NGINX_CONTAINER" ]; then echo "Error: No nginx-proxy container found running" exit 1 fi NGINX_UID=$(docker exec ${NGINX_CONTAINER} id -u nginx) NGINX_GID=$(docker exec ${NGINX_CONTAINER} id -g nginx) mkdir -p /var/log/nginx/healthd chown -R ${NGINX_UID}:${NGINX_GID} /var/log/nginx ``` ## Step 2: Run your application locally Use the [docker compose up](https://docs.docker.com/compose/reference/up/) command to build and run your multi-container application locally. Docker Compose will build both container images and start the services defined in your `docker-compose.yml` file. ``` ~/eb-docker-compose-flask$ docker compose up --build ``` The **--build** option ensures that Docker Compose builds the container images before starting the services. You should see output showing both the web service and nginx-proxy service starting up. Navigate to `http://localhost` in your browser. You should see the text "Hello Elastic Beanstalk\$1 This is a Docker Compose application". The nginx proxy receives your request on port 80 and forwards it to the Flask application running on port 5000. When you're finished testing, stop the application by pressing **Ctrl\$1C** in the terminal, or run the following command in a separate terminal: ``` ~/eb-docker-compose-flask$ docker compose down ``` ## Step 3: Deploy your Docker Compose application with the EB CLI Run the following commands to create an Elastic Beanstalk environment for this application. **To create an environment and deploy your Docker Compose application** 1. Initialize your EB CLI repository with the **eb init** command. ``` ~/eb-docker-compose-flask$ eb init -p docker docker-compose-tutorial --region us-east-2 Application docker-compose-tutorial has been created. ``` This command creates an application named `docker-compose-tutorial` and configures your local repository to create environments with the latest Docker platform version. 1. (Optional) Run **eb init** again to configure a default key pair so that you can use SSH to connect to the EC2 instance running your application. ``` ~/eb-docker-compose-flask$ eb init Do you want to set up SSH for your instances? (y/n): y Select a keypair. 1) my-keypair 2) [ Create new KeyPair ] ``` Select a key pair if you have one already, or follow the prompts to create one. If you don't see the prompt or need to change your settings later, run **eb init -i**. 1. Create an environment and deploy your application to it with **eb create**. Elastic Beanstalk automatically detects your `docker-compose.yml` file and deploys your multi-container application. ``` ~/eb-docker-compose-flask$ eb create docker-compose-tutorial ``` It takes about five minutes for Elastic Beanstalk to create your environment and deploy your multi-container application. ## Step 4: Test your application on Elastic Beanstalk When the process to create your environment completes, open your website with **eb open**. ``` ~/eb-docker-compose-flask$ eb open ``` Great\$1 You've deployed a multi-container Docker Compose application with Elastic Beanstalk\$1 This opens a browser window using the domain name created for your application. You should see the message from your Flask application, served through the nginx reverse proxy. ## Step 5: Clean up You can terminate your environment when you finish working with your application. Elastic Beanstalk terminates all AWS resources associated with your environment. To terminate your Elastic Beanstalk environment with the EB CLI run the following command. ``` ~/eb-docker-compose-flask$ eb terminate ``` ## AWS resources for your application You just created a single instance application running multiple containers. It serves as a straightforward sample application with a single EC2 instance, so it doesn't require load balancing or auto scaling. For single instance applications Elastic Beanstalk creates the following AWS resources: + **EC2 instance** – An Amazon EC2 virtual machine configured to run web apps on the platform you choose. Each platform runs a different set of software, configuration files, and scripts to support a specific language version, framework, web container, or combination thereof. Most platforms use either Apache or nginx as a reverse proxy that processes web traffic in front of your web app, forwards requests to it, serves static assets, and generates access and error logs. + **Instance security group** – An Amazon EC2 security group configured to allow incoming traffic on port 80. This resource lets HTTP traffic from the load balancer reach the EC2 instance running your web app. By default, traffic is not allowed on other ports. + **Amazon S3 bucket** – A storage location for your source code, logs, and other artifacts that are created when you use Elastic Beanstalk. + **Amazon CloudWatch alarms** – Two CloudWatch alarms that monitor the load on the instances in your environment and are triggered if the load is too high or too low. When an alarm is triggered, your Auto Scaling group scales up or down in response. + **CloudFormation stack** – Elastic Beanstalk uses CloudFormation to launch the resources in your environment and propagate configuration changes. The resources are defined in a template that you can view in the [CloudFormation console](https://console.aws.amazon.com/cloudformation). + **Domain name** – A domain name that routes to your web app in the form **subdomain*.*region*.elasticbeanstalk.com*. Elastic Beanstalk manages all of these resources. When you terminate your environment, Elastic Beanstalk terminates all the resources that it contains. Your Docker Compose application runs multiple containers on the single EC2 instance, with Elastic Beanstalk handling the orchestration automatically. ## Next steps After you have an environment running an application, you can deploy a new version of the application or a different application at any time. Deploying a new application version is very quick because it doesn't require provisioning or restarting EC2 instances. You can also explore your new environment using the Elastic Beanstalk console. For detailed steps, see [Explore your environment](GettingStarted.md#GettingStarted.Explore) in the *Getting started* chapter of this guide. After you deploy a sample application or two and are ready to start developing and running Docker Compose applications locally, see [Preparing your Docker image for deployment to Elastic Beanstalk](single-container-docker-configuration.md). ## Deploy with the Elastic Beanstalk console You can also use the Elastic Beanstalk console to launch a Docker Compose application. Create a ZIP file containing your `docker-compose.yml` file and all associated directories and files, then upload it when creating a new application. For detailed steps, see [Create an example application](GettingStarted.md#GettingStarted.CreateApp) in the *Getting started* chapter of this guide. # Preparing your Docker image for deployment to Elastic Beanstalk This section describes how to prepare your Docker image for deployment to Elastic Beanstalk with either of the *Docker running AL2 or AL2023* platform branches. The configuration files that you'll require depend on whether your images are local, remote, and if you're using Docker Compose. **Note** For an example of a procedure that launches a Docker environment see the [QuickStart for Docker](docker-quickstart.md) topic. **Topics** + [ ## Managing your images with Docker Compose in Elastic Beanstalk ](#single-container-docker-configuration-dc) + [ ## Managing images without Docker Compose in Elastic Beanstalk ](#single-container-docker-configuration.no-compose) + [ ## Building custom images with a Dockerfile ](#single-container-docker-configuration.dockerfile) ## Managing your images with Docker Compose in Elastic Beanstalk You may choose to use Docker Compose to manage various services in one YAML file. To learn more about Docker Compose see [Why use Compose?](https://docs.docker.com/compose/intro/features-uses/) on the Docker website. + Create a `docker-compose.yml`. This file is required if you're using Docker Compose to manage your application with Elastic Beanstalk. If all your deployments are sourced from images in public repositories, then no other configuration files are required. If your deployment's source images are in a private repository, you'll need to do some additional configuration. For more information, see [Using images from a private repository](docker-configuration.remote-repo.md). For more information about the `docker-compose.yml` file, see [Compose file reference](https://docs.docker.com/compose/compose-file/) on the Docker website. + The `Dockerfile` is optional. Create one if you need Elastic Beanstalk to build and run a local custom image. For more information about the `Dockerfile` see [Dockerfile reference](https://docs.docker.com/engine/reference/builder/) on the Docker website. + You may need to create a `.zip` file. If you use only a `Dockerfile` file to deploy your application, you don't need to create one. If you use additional configuration files the .zip file must include the `Dockerfile`, the `docker-compose.yml` file, your application files, and any application file dependencies. The `Dockerfile` and the `docker-compose.yml` must be at the root, or top level, of the .zip archive. If you use the EB CLI to deploy your application, it creates a .zip file for you. 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/). ## Managing images without Docker Compose in Elastic Beanstalk If you're not using Docker Compose to manage your Docker images, you'll need to configure a `Dockerfile`, a `Dockerrun.aws.json` file, or both. + Create a `Dockerfile` to have Elastic Beanstalk build and run a custom image locally. + Create a `Dockerrun.aws.json v1` file to deploy a Docker image from a hosted repository to Elastic Beanstalk. + You may need to create a `.zip` file. If you use *only one* of either file, the `Dockerfile` or the `Dockerrun.aws.json`, then you don't need to create a .zip file. If you use both files, then you do need a .zip file. The .zip file must include both the `Dockerfile` and the `Dockerrun.aws.json`, along with the file containing your application files plus any application file dependencies. If you use the EB CLI to deploy your application, it creates a `.zip` file for you. ### `Dockerrun.aws.json` v1 configuration file A `Dockerrun.aws.json` file describes how to deploy a remote Docker image as an Elastic Beanstalk application. This JSON file is specific to Elastic Beanstalk. If your application runs on an image that is available in a hosted repository, you can specify the image in a `Dockerrun.aws.json v1` file and omit the `Dockerfile`. **`Dockerrun.aws.json` versions** The `AWSEBDockerrunVersion` parameter indicates the version of the `Dockerrun.aws.json` file. The Docker AL2 and AL2023 platforms use the following versions of the file. `Dockerrun.aws.json v3` — environments that use Docker Compose. `Dockerrun.aws.json v1` — environments that do not use Docker Compose. *ECS running on Amazon Linux 2* and *ECS running on AL2023* uses the `Dockerrun.aws.json v2` file. The retired platform *ECS-The Multicontainer Docker Amazon Linux AMI (AL1)* also used this same version. #### Dockerrun.aws.json v1 Valid keys and values for the `Dockerrun.aws.json v1` file include the following operations: **AWSEBDockerrunVersion** (Required) Specify the version number `1` if you're not using Docker Compose to manage your image. **Authentication** (Required only for private repositories) Specifies the Amazon S3 object storing the `.dockercfg` file. See [Authenticating with image repositoriesUsing AWS Secrets Manager](docker-configuration.remote-repo.md#docker-configuration.remote-repo.dockerrun-aws) in *Using images from a private repository* later in this chapter. **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 */* for images on Docker Hub, or *//* for other sites. When you specify an image in the `Dockerrun.aws.json` file, each instance in your Elastic Beanstalk environment runs `docker pull` to run the image. Optionally, include the **Update** key. The default value is `true` and instructs Elastic Beanstalk to check the repository, pull any updates to the image, and overwrite any cached images. When using a `Dockerfile`, do not specify the **Image** key in the `Dockerrun.aws.json` file. Elastic Beanstalk always builds and uses the image described in the `Dockerfile` when one is present. **Ports** (Required when you specify the **Image** key) Lists the ports to expose on the Docker container. Elastic Beanstalk uses the **ContainerPort** value to connect the Docker container to the reverse proxy running on the host. You can specify multiple container ports, but Elastic Beanstalk uses only the first port. It uses this port to connect your container to the host's reverse proxy and route requests from the public internet. If you're using a `Dockerfile`, the first **ContainerPort** value should match the first entry in the `Dockerfile`'s **EXPOSE** list. Optionally, you can specify a list of ports in **HostPort**. **HostPort** entries specify the host ports that **ContainerPort** values are mapped to. If you don't specify a **HostPort** value, it defaults to the **ContainerPort** value. ``` { "Image": { "Name": "image-name" }, "Ports": [ { "ContainerPort": 8080, "HostPort": 8000 } ] } ``` ****Volumes**** Map volumes from an EC2 instance to your Docker container. Specify one or more arrays of volumes to map. ``` { "Volumes": [ { "HostDirectory": "/path/inside/host", "ContainerDirectory": "/path/inside/container" } ] ... ``` ****Logging**** Specify the directory inside the container to which your application writes logs. Elastic Beanstalk uploads any logs in this directory to Amazon S3 when you request tail or bundle logs. If you rotate logs to a folder named `rotated` within this directory, you can also configure Elastic Beanstalk to upload rotated logs to Amazon S3 for permanent storage. For more information, see [Viewing logs from Amazon EC2 instances in your Elastic Beanstalk environment](using-features.logging.md). **Command** Specify a command to run in the container. If you specify an **Entrypoint**, then **Command** is added as an argument to **Entrypoint**. For more information, see [CMD](https://docs.docker.com/engine/reference/run/#cmd-default-command-or-options) in the Docker documentation. **Entrypoint** Specify a default command to run when the container starts. For more information, see [ENTRYPOINT](https://docs.docker.com/engine/reference/run/#cmd-default-command-or-options) in the Docker documentation. The following snippet is an example that illustrates the syntax of the `Dockerrun.aws.json` file for a single container. ``` { "AWSEBDockerrunVersion": "1", "Image": { "Name": "janedoe/image", "Update": "true" }, "Ports": [ { "ContainerPort": "1234" } ], "Volumes": [ { "HostDirectory": "/var/app/mydb", "ContainerDirectory": "/etc/mysql" } ], "Logging": "/var/log/nginx", "Entrypoint": "/app/bin/myapp", "Command": "--argument" }> ``` You can provide Elastic Beanstalk with only the `Dockerrun.aws.json` file, or with a `.zip` archive containing both the `Dockerrun.aws.json` and `Dockerfile` files. When you provide both files, the `Dockerfile` describes the Docker image and the `Dockerrun.aws.json` file provides additional information for deployment, as described later in this section. **Note** The two files must be at the root, or top level, of the `.zip` archive. Don't build the archive from a directory containing the files. Instead, navigate into that directory and build the archive there. When you provide both files, don't specify an image in the `Dockerrun.aws.json` file. Elastic Beanstalk builds and uses the image described in the `Dockerfile` and ignores the image specified in the `Dockerrun.aws.json` file. ## Building custom images with a Dockerfile You need to create a `Dockerfile` if you don't already have an existing image hosted in a repository. The following snippet is an example of the `Dockerfile`. If you follow the instructions in [QuickStart for Docker](docker-quickstart.md), you can upload this `Dockerfile` as written. Elastic Beanstalk runs the game 2048 when you use this `Dockerfile`. For more information about instructions you can include in the `Dockerfile`, see [Dockerfile reference](https://docs.docker.com/engine/reference/builder) on the Docker website. ``` 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"] ``` **Note** You can run multi-stage builds from a single Dockerfile to produce smaller-sized images with a significant reduction in complexity. For more information, see [Use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) on the Docker documentation website.