Docker Engine on AWS User Guide

Overview

This image runs Docker Engine, the open source container runtime, fully installed and configured from the official Docker package repository. Docker Engine, the Docker command line client, the containerd runtime, the Buildx build plugin and the Compose plugin are all in place, and the Docker daemon and containerd start automatically at boot.

Container image layers, container writable layers and named volumes are stored on a separate, independently resizable storage volume mounted at the Docker data directory, so the container store is kept off the operating system disk and can be grown without disturbing the rest of the instance.

On the first boot of every deployed instance, a one shot service adds the default login user to the docker group, so containers can be managed without sudo after a single re-login. A short information file at /stage/scripts/docker-info.log records the installed engine version and how container access is granted. This file contains no secrets, because Docker has no daemon level credentials to rotate: access to the container socket is governed entirely by Linux group membership.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
• The AWS CLI version 2 installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Docker Engine. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger as a balanced default; size the instance to the container workload you intend to run. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network. If you intend to publish a containerized service, also open the port that service listens on. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes only a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Docker Engine Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}' \
  --metadata-options 'HttpTokens=required,HttpEndpoint=enabled' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=docker-engine}]'

The image attaches a dedicated 20 GiB container storage volume automatically, mounted at the Docker data directory. To start with more container storage, enlarge that volume on the Storage step in the console, or add a second block device mapping on the CLI.

Step 3: Connect to the Instance over SSH

Connect to the instance with SSH as the default login user for the operating system variant you launched. The login user differs by variant:

Replace <key-file> with the path to your private key file and <instance-public-ip> with the public IP address or DNS name of the instance.

ssh -i <key-file> ubuntu@<instance-public-ip>

The login user is added to the docker group on the instance's first boot. If you connect during the very first few seconds after launch, log out and reconnect once so your shell session picks up the new group membership. After that, the docker commands below run without sudo.

Step 4: Confirm the Docker Engine

Check the installed engine, the API version and the runtime components. The client and server versions match, and the containerd and runc runtime versions are reported by the server.

docker version

Confirm the Buildx and Compose plugins and the containerd runtime are present:

docker compose version
docker buildx version
containerd --version

The instance information file records the installed engine version and how container access is granted. It holds no secrets:

cat /stage/scripts/docker-info.log

Step 5: Run Your First Container

Run the hello-world image. Docker pulls the image from Docker Hub, creates a container from it, runs it, and prints a confirmation message. This is the quickest end to end check that the engine is working.

docker run hello-world

Run a longer lived container in the background. The following command starts an nginx web server, names the container web, and publishes container port 80 on host port 8080:

docker run -d --name web -p 8080:80 nginx:alpine

List the running containers and confirm the port mapping:

docker ps

Step 6: Define a Multi Container Application with Compose

The Compose plugin runs multi container applications from a single declarative file. Create a working directory and a compose.yaml file describing the services. The example below defines one nginx web service publishing host port 8080.

mkdir -p ~/web-demo && cd ~/web-demo
cat > compose.yaml <<'EOF'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    restart: unless-stopped
EOF

Bring the application up in the background with docker compose up -d, then list its services with docker compose ps. Compose creates a dedicated network for the application and starts each service as a container.

To stop the application and remove its containers and network, run docker compose down from the same directory.

Step 7: Build an Image

Docker builds images from a Dockerfile. Create a small build context and a Dockerfile, then build a tagged image with docker build:

mkdir -p ~/build-demo && cd ~/build-demo
cat > Dockerfile <<'EOF'
FROM alpine:3
RUN echo "Built with Docker Engine on cloudimg" > /message
CMD ["cat", "/message"]
EOF
docker build -t my-app:1.0 .
docker run --rm my-app:1.0

For advanced and multi platform builds, use the Buildx plugin with docker buildx build. Buildx is preinstalled and ready.

Step 8: Engine and Container Storage

The Docker daemon and the containerd runtime run as systemd services and start automatically at boot. Confirm their status with:

systemctl is-active docker.service containerd.service

Container image layers, container writable layers and named volumes are stored under the Docker data directory, which is a separate filesystem on its own EBS volume. Confirm the dedicated mount and review free space with:

findmnt /var/lib/docker
df -h /var/lib/docker

Because the container store is on its own volume, you can grow it independently of the operating system disk. Modify the EBS volume in the AWS console or with the CLI, then extend the filesystem on the instance with resize2fs against the volume's device.

Step 9: Maintenance

Keep the operating system patched with the standard package manager. To upgrade the Docker Engine itself, the official Docker APT repository is already configured on the image, so engine upgrades are delivered through the normal package update process.

Reclaim disk space by removing unused images, stopped containers and dangling build cache with docker system prune. Review what is currently using space with docker system df.

docker system df

To allow another Linux user to manage containers without sudo, add that user to the docker group and have them start a new login session.

sudo usermod -aG docker <username>

Support

This Amazon Machine Image is provided by cloudimg with 24/7 technical support by email and chat. Contact cloudimg for help with container deployment, image building, Compose orchestration, storage configuration and engine upgrades.

Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. All other product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.