Running a Docker environment locally with the EB CLI - Amazon Elastic Beanstalk
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Running a Docker environment locally with the EB CLI

You can use the Elastic Beanstalk Command Line Interface (EB CLI) to run the Docker containers configured in your Amazon Elastic Beanstalk application locally. The EB CLI uses the Docker configuration file (Dockerfile or and source code in your project directory to run your application locally in Docker.

Prerequisites for running Docker applications locally

  • Linux OS or Mac OS X

  • EB CLI version 3.3 or greater

    Run eb init in your project directory to initialize an EB CLI repository. If you haven't used the EB CLI before, see Managing Elastic Beanstalk environments with the EB CLI.

  • Docker version 1.6 or greater

    Add yourself to the docker group, log out, and then log back in to ensure that you can run Docker commands without sudo:

    $ sudo usermod -a -G docker $USER

    Run docker ps to verify that the Docker daemon is up and running:

  • A Docker application

    If you don't have a Docker application in a project folder on your local machine, see Deploying Elastic Beanstalk applications from Docker containers for an introduction to using Docker with Amazon Elastic Beanstalk.

  • Docker profile (optional)

    If your application uses Docker images that are in a private repository, run docker login and follow the prompts to create an authentication profile.

  • w3m (optional)

    W3m is a web browser that you can use to view your running web application within a command line terminal with eb local run. If you are using the command line in a desktop environment, you don't need w3m.

Docker containers run locally without emulating Amazon resources that are provisioned when you deploy an application to Elastic Beanstalk, including security groups and data or worker tiers.

You can configure your local containers to connect to a database by passing the necessary connection string or other variables with the envvars option, but you must ensure that any resources in Amazon are accessible from your local machine by opening the appropriate ports in their assigned security groups or attaching a default gateway or elastic IP address.

Preparing a Docker application for use with the EB CLI

Prepare your Docker configuration file and source data as though you were deploying them to Elastic Beanstalk. This topic uses the PHP and nginx proxy example from the Multi-container Docker tutorial, which is also in this chapter. You can use the same commands with any Docker, Multi-container Docker, or Preconfigured Docker application.

Running a Docker application locally

Run your Docker application locally with the eb local run command from within the project directory:

~/project$ eb local run Creating elasticbeanstalk_phpapp_1... Creating elasticbeanstalk_nginxproxy_1... Attaching to elasticbeanstalk_phpapp_1, elasticbeanstalk_nginxproxy_1 phpapp_1 | [23-Apr-2015 23:24:25] NOTICE: fpm is running, pid 1 phpapp_1 | [23-Apr-2015 23:24:25] NOTICE: ready to handle connections

The EB CLI reads the Docker configuration and executes the Docker commands necessary to run your application. The first time you run a project locally, Docker downloads images from a remote repository and stores them on your local machine. This process can take several minutes.


The eb local run command takes two optional parameters, port and envvars.

To override the default port for a Docker application, use the port option:

$ eb local run --port 8080

This command tells the EB CLI to use port 8080 on the host and map it to the exposed port on the container. If you don't specify a port, the EB CLI uses the container's port for the host. This option only works with applications using the Docker platform.

To pass environment variables to the application containers, use the envvars option:


Use environment variables to configure a database connection, set debug options, or pass secrets securely to your application. For more information on the options supported by the eb local subcommands, see eb local.

After the containers are up and running in Docker, they are ready to take requests from clients. The eb local process stays open as long as the containers are running. If you need to stop the process and containers, press Ctrl+C.

Open a second terminal to run additional commands while the eb local process is running. Use eb local status to view your application's status:

~/project$ eb local status Platform: 64bit Amazon Linux 2014.09 v1.2.1 running Multi-container Docker 1.3.3 (Generic) Container name: elasticbeanstalk_nginxproxy_1 Container ip: Container running: True Exposed host port(s): 80 Full local URL(s): Container name: elasticbeanstalk_phpapp_1 Container ip: Container running: True Exposed host port(s): None Full local URL(s): None

You can use docker ps to see the status of the containers from Docker's point of view:

~/project$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 6a8e71274fed nginx:latest "nginx -g 'daemon of 9 minutes ago Up 9 minutes>80/tcp, 443/tcp elasticbeanstalk_nginxproxy_1 82cbf620bdc1 php:fpm "php-fpm" 9 minutes ago Up 9 minutes 9000/tcp elasticbeanstalk_phpapp_1

Next, view your application in action with eb local open:

~/project$ eb local open

This command opens your application in the default web browser. If you are running a terminal in a desktop environment, this may be Firefox, Safari, or Google Chrome. If you are running a terminal in a headless environment or over an SSH connection, a command line browser, such as w3m, will be used if one is available.

Switch back to the terminal running the application process for a moment and note the additional output:

phpapp_1 | - 21/Apr/2015:23:46:17 +0000 "GET /index.php" 200

This shows that the web application in the Docker container received an HTTP GET request for index.php that was returned successfully with a 200 (non error) status.

Run eb local logs to see where the EB CLI writes the logs.

~/project$ eb local logs Elastic Beanstalk will write logs locally to /home/user/project/.elasticbeanstalk/logs/local. Logs were most recently created 3 minutes ago and written to /home/user/project/.elasticbeanstalk/logs/local/150420_234011665784.

Cleaning up after running a Docker application locally

When you are done testing your application locally, you can stop the applications and remove the images downloaded by Docker when you use eb local run. Removing the images is optional. You may want to keep them for future use.

Return to the terminal running the eb local process and press Ctrl+C to stop the application:

^CGracefully stopping... (press Ctrl+C again to force) Stopping elasticbeanstalk_nginxproxy_1... Stopping elasticbeanstalk_phpapp_1... Aborting. [1]+ Exit 5 eb local run

The EB CLI attempts to stop each running container gracefully with Docker commands. If you need to stop a process immediately, press Ctrl+C again.

After you stop the applications, the Docker containers should also stop running. Verify this with docker ps:

$ docker ps --all CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 73d515d99d2a nginx:latest "nginx -g 'daemon of 21 minutes ago Exited (0) 11 minutes ago elasticbeanstalk_nginxproxy_1 7061c76220de php:fpm "php-fpm" 21 minutes ago Exited (0) 11 minutes ago elasticbeanstalk_phpapp_1

The all option shows stopped containers (if you omitted this option, the output will be blank). In the above example, Docker shows that both containers exited with a 0 (non-error) status.

If you are done using Docker and EB CLI local commands, you can remove the Docker images from your local machine to save space.

To remove Docker images from your local machine
  1. View the images that you downloaded using docker images:

    $ docker images REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE php fpm 68bc5150cffc 1 hour ago 414.1 MB nginx latest 637d3b2f5fb5 1 hour ago 93.44 MB
  2. Remove the two Docker containers with docker rm:

    $ docker rm 73d515d99d2a 7061c76220de 73d515d99d2a 7061c76220de
  3. Remove the images with docker rmi:

    $ docker rmi 68bc5150cffc 637d3b2f5fb5 Untagged: php:fpm Deleted: 68bc5150cffc0526c66b92265c3ed8f2ea50f3c71d266aa655b7a4d20c3587b0 Untagged: nginx:latest Deleted: 637d3b2f5fb5c4f70895b77a9e76751a6e7670f4ef27a159dad49235f4fe61e0