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 Amazon Elastic Beanstalk environment. You'll create a Flask web application with an nginx reverse proxy to demonstrate how Docker Compose simplifies orchestrating multiple containers.

Your Amazon account

If you're not already an Amazon customer, you need to create an Amazon account. Signing up enables you to access Elastic Beanstalk and other Amazon services that you need.

If you already have an Amazon account, you can move on to Prerequisites.

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 ($) 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 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) and Configure the EB CLI.

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 and Install Docker Compose 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.

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.

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.

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.

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.

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.

#!/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 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! 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+C 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.

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! You've deployed a multi-container Docker Compose application with Elastic Beanstalk! 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 Amazon 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

Amazon 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 Amazon resources:

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

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 in the Getting started chapter of this guide.