How to Install Docker on an EC2 Instance

Summary:

• Learn how to install Docker on EC2 instances running Amazon Linux 2 and Amazon Linux 2023, with step-by-step commands for each AMI version and guidance on choosing the right approach for your workloads.
• Understand the critical differences between AL2 and AL2023 package management, including the shift from amazon-linux-extras to native dnf repositories and Docker version 25 availability.
• Configure rootless Docker, Docker Compose plugin, and daemon.json settings to establish production-ready container infrastructure with proper security hardening on your EC2 instances.
• Navigate the AL2 deprecation timeline and plan your final migration strategy to AL2023 before the June 30, 2026 end-of-life deadline.

Running containers on AWS infrastructure remains one of the most common deployment patterns for modern applications. However, the process to install Docker on an EC2 instance has evolved significantly with the release of Amazon Linux 2023. Engineers who learned Docker installation on Amazon Linux 2 now face a different package management landscape, updated security defaults, and new decisions around rootless execution modes.

This guide provides the definitive walkthrough for both AMI versions. It addresses the deprecation timeline that makes this knowledge urgent and equips you with production-grade configurations that go far beyond basic installation.

The following diagram illustrates the high-level architecture of Docker running on an EC2 instance, including the relationship between the Docker daemon, containerd runtime, user permissions, and network security boundaries.

Understanding Amazon Linux AMI versions and Docker support

Before executing any installation commands, you must understand which Amazon Machine Image your EC2 instance runs and what that means for Docker availability. Amazon Linux 2 (AL2) has been the workhorse AMI since 2018, but its official end-of-life date arrives on June 30, 2026. Amazon Linux 2023 (AL2023) became generally available in March 2023 and represents the future of AWS-optimized Linux distributions.

The Docker installation process differs substantially between these two AMI versions due to fundamental changes in package management philosophy.

Amazon Linux 2 uses the amazon-linux-extras repository system to provide newer software packages outside the base repositories. Docker on AL2 historically shipped through this extras mechanism, though AWS released Docker version 25 as a direct update in mid-2024 through security advisory ALAS-2024-009.

Amazon Linux 2023 abandons the extras concept entirely. Instead, it provides Docker directly through the standard dnf package manager with versioned repositories. This shift simplifies installation but requires different commands than engineers familiar with AL2 might expect.

The table below provides a comprehensive comparison of Docker support across Amazon Linux versions and other common EC2 operating systems, helping you make informed decisions about AMI selection.

With this foundation established, the next section walks through the prerequisites and EC2 instance configuration required before Docker installation begins.

Prerequisites and EC2 instance setup

Successful Docker installation requires proper EC2 instance configuration from the start. The instance type, IAM permissions, security group rules, and storage allocation all impact your container workloads. Taking time to configure these elements correctly prevents troubleshooting sessions later when containers fail to pull images or communicate with external services.

Instance type and resource requirements

Docker itself has minimal resource requirements, but your containerized applications determine the appropriate instance sizing. For development and testing purposes, a t3.micro or t3.small instance provides sufficient resources. Production workloads typically require at least a t3.medium with 4GB of memory to handle multiple containers, image layer caching, and build operations.

Consider the following baseline requirements:

• CPU: Minimum 1 vCPU for light workloads, 2+ vCPUs for builds and multi-container deployments
• Memory: 1GB absolute minimum, 4GB recommended for production
• Storage: 20GB root volume minimum, with additional EBS volumes for persistent container data

IAM role and security group configuration

Attach an IAM role to your EC2 instance that grants permissions for Amazon Elastic Container Registry (ECR) if you plan to pull private images. The AmazonEC2ContainerRegistryReadOnly managed policy provides sufficient permissions for most use cases.

Your security group must allow outbound HTTPS traffic on port 443 for Docker to pull images from registries. If running web applications in containers, add inbound rules for the appropriate application ports.

With your EC2 instance properly configured, you can proceed to the installation steps specific to your AMI version. The following section covers Amazon Linux 2 installation for those maintaining existing infrastructure.

Install Docker on Amazon Linux 2

Amazon Linux 2 installation leverages either the amazon-linux-extras repository or direct yum installation, depending on your timing and update status. The amazon-linux-extras approach was the original method, but recent updates have made Docker available directly through standard yum repositories. Both methods result in a functional Docker installation, though the direct yum method now provides Docker version 25 with the latest security patches.

Connect to your EC2 instance via SSH and execute the following commands to install Docker using the recommended direct method:

# Update all packages to latest versions
sudo yum update -y

# Install Docker directly from yum repositories
sudo yum install docker -y

# Start the Docker daemon
sudo systemctl start docker

# Enable Docker to start on boot
sudo systemctl enable docker

# Verify installation
docker --version

The alternative amazon-linux-extras method remains available for environments where you need explicit control over the Docker topic version:

# Enable Docker through extras
sudo amazon-linux-extras enable docker

# Install Docker package
sudo yum install docker -y

# Start and enable the service
sudo systemctl start docker
sudo systemctl enable docker

Adding ec2-user to the docker group

By default, the Docker daemon socket is owned by root, requiring sudo for every Docker command. Adding your user to the docker group eliminates this friction while maintaining security through group-based access control. Execute the following command and then log out and back in for the group membership to take effect:

# Add ec2-user to docker group
sudo usermod -aG docker ec2-user

# Log out and back in, then verify
exit
# Reconnect via SSH
docker ps

Amazon Linux 2 installations should now be fully functional. However, given the approaching deprecation deadline, the next section covers the preferred installation path on Amazon Linux 2023.

Install Docker on Amazon Linux 2023

Amazon Linux 2023 streamlines Docker installation by including it in the standard dnf repositories without requiring extras or third-party repository configuration. The dnf package manager replaces yum as the default, though yum commands still work as dnf aliases for backward compatibility. This section provides the canonical installation procedure for AL2023 instances launched after March 2023.

The following diagram shows the package management flow on AL2023, illustrating how dnf retrieves Docker packages from AWS-maintained repositories.

Execute these commands on a fresh AL2023 instance to install Docker:

# Update system packages
sudo dnf update -y

# Install Docker
sudo dnf install docker -y

# Start Docker daemon
sudo systemctl start docker

# Enable Docker on boot
sudo systemctl enable docker

# Add ec2-user to docker group
sudo usermod -aG docker ec2-user

# Verify installation
sudo docker version

After adding your user to the docker group, disconnect your SSH session and reconnect for the group membership to activate. You can then run Docker commands without sudo privileges.

Verifying the installation

A successful installation should report both client and server versions when running docker version. Test container execution by pulling and running the hello-world image:

# Test Docker functionality
docker run hello-world

# Check running containers
docker ps -a

# Inspect Docker system information
docker info

The docker info command reveals important details about your installation, including the storage driver (overlay2 on AL2023), the number of CPUs and memory available to containers, and the containerd runtime version. With basic installation complete, the next section explores advanced configurations including rootless mode and Docker Compose.

Rootless Docker and Docker Compose plugin

Rootless Docker runs the daemon and containers entirely within a user namespace, eliminating the security risks associated with a root-owned daemon. This configuration prevents container escape vulnerabilities from granting host root access, making it increasingly popular for security-conscious deployments. Amazon Linux 2023 supports rootless Docker, though it requires additional package installation and configuration.

Configuring rootless Docker on AL2023

Rootless mode requires the installation of additional user namespace tools and modifications to your user environment. The following steps configure rootless Docker for the ec2-user account:

# Install rootless prerequisites
sudo dnf install -y fuse-overlayfs iptables

# Install rootless Docker components
sudo dnf install -y docker-rootless-extras

# Configure user namespace delegation
sudo sh -c 'echo "ec2-user:100000:65536" >> /etc/subuid'
sudo sh -c 'echo "ec2-user:100000:65536" >> /etc/subgid'

# Run rootless setup as ec2-user
dockerd-rootless-setuptool.sh install

# Start rootless daemon
systemctl --user start docker

# Enable on login
systemctl --user enable docker

Installing Docker Compose plugin

Docker Compose enables multi-container application definitions through declarative YAML files. The modern installation method uses the Docker CLI plugin architecture rather than the standalone docker-compose binary. On AL2023, install the Compose plugin with:

# Install Docker Compose plugin
sudo dnf install docker-compose-plugin -y

# Verify installation
docker compose version

Note the command syntax difference. The plugin uses docker compose (space) rather than the legacy docker-compose (hyphen). Both syntaxes work if you install the standalone binary, but the plugin approach receives updates through standard package management.

Consider the following when choosing between rootless and standard Docker modes:

1. Security requirements: Rootless mode provides defense-in-depth against container escapes but adds complexity
2. Port binding: Rootless containers cannot bind to ports below 1024 without additional configuration
3. Performance: Rootless mode incurs slight overhead from user namespace translation
4. Compatibility: Some container images assume root privileges and fail in rootless mode

With Docker and Compose installed, the next section covers daemon configuration options that optimize Docker for production EC2 workloads.

Configuring the Docker daemon

The Docker daemon accepts configuration through command-line flags or the daemon.json configuration file. The file-based approach provides persistent configuration that survives daemon restarts and simplifies infrastructure-as-code management. On both AL2 and AL2023, the configuration file lives at /etc/docker/daemon.json and must contain valid JSON.

Create or modify the daemon configuration file with settings appropriate for EC2 environments:

# Create Docker configuration directory if needed
sudo mkdir -p /etc/docker

# Create daemon.json with production settings
sudo tee /etc/docker/daemon.json > /dev/null <<eof {="" "log-driver":="" "json-file",="" "log-opts":="" "max-size":="" "100m",="" "max-file":="" "3"="" },="" "storage-driver":="" "overlay2",="" "live-restore":="" true,="" "userland-proxy":="" false,="" "default-ulimits":="" "nofile":="" "name":="" "nofile",="" "hard":="" 65536,="" "soft":="" 65536="" }="" eof="" #="" restart="" docker="" to="" apply="" changes="" sudo="" systemctl="" docker

Key configuration options explained:

• log-driver and log-opts: Prevents container logs from consuming unlimited disk space
• storage-driver: overlay2 provides the best performance on modern kernels
• userland-proxy: Disabling uses iptables directly for better performance
• default-ulimits: Increases file descriptor limits for high-connection applications

Daemon configuration establishes the foundation for reliable container operations. The following section addresses version management and migration strategies for teams moving from AL2 to AL2023.

Version upgrades and AL2 to AL2023 migration

Managing Docker versions across your EC2 fleet requires understanding the upgrade paths available on each AMI. Amazon Linux 2 received Docker version 25 through security updates in 2024, bringing it to feature parity with AL2023. However, the underlying system differences mean migration involves more than simply updating packages.

The following diagram illustrates the migration decision tree for teams planning their transition from AL2 to AL2023.

Upgrading Docker on Amazon Linux 2

If you must remain on AL2 temporarily, ensure you have the latest Docker version with security patches:

# Check current version
docker version

# Update Docker package
sudo yum update docker -y

# Restart daemon
sudo systemctl restart docker

# Verify upgrade
docker version

Migration strategy to AL2023

In-place upgrades from AL2 to AL2023 are not supported. Migration requires provisioning new instances and transferring workloads. Follow this sequence for production migrations:

1. Inventory existing containers: Document all running containers, volumes, and network configurations
2. Export persistent data: Back up Docker volumes to S3 or EBS snapshots
3. Provision AL2023 instances: Launch new instances with equivalent or updated specifications
4. Install and configure Docker: Apply your daemon.json and security configurations
5. Restore data and deploy: Import volumes and start containers from your orchestration tooling

Watch out: Scripts that reference amazon-linux-extras will fail on AL2023. Audit your automation and user data scripts for AL2-specific commands before migration.

With migration planning addressed, the next section covers security hardening measures that protect your Docker installation from common attack vectors.

Security hardening for Docker on EC2

Docker security extends beyond installation to encompass daemon configuration, container runtime restrictions, and network isolation. EC2 instances running Docker face threats from both external attackers and potentially malicious container images. Implementing defense-in-depth protections reduces risk across multiple attack surfaces.

Daemon and host security

Secure your Docker daemon with these configuration additions to daemon.json:

{
  "icc": false,
  "no-new-privileges": true,
  "userns-remap": "default"
}

These settings provide:

• icc: false: Disables inter-container communication on the default bridge network, requiring explicit links
• no-new-privileges: Prevents containers from gaining additional privileges through setuid binaries
• userns-remap: Maps container root to an unprivileged host user

Container runtime restrictions

Apply runtime security options when starting containers to limit their capabilities:

# Run container with security restrictions
docker run -d \
  --security-opt=no-new-privileges:true \
  --cap-drop=ALL \
  --cap-add=NET_BIND_SERVICE \
  --read-only \
  --tmpfs /tmp \
  nginx:latest

Real-world context: The principle of least privilege applies directly to container capabilities. Most applications need only a fraction of the default Linux capabilities. Dropping all capabilities and adding back only required ones significantly reduces the blast radius of container compromises.

Security hardening represents an ongoing process rather than a one-time configuration. The final technical section addresses common troubleshooting scenarios encountered during Docker installation and operation.

Troubleshooting common installation issues

Docker installation failures typically stem from permission problems, service configuration errors, or network connectivity issues. Understanding the diagnostic approach for each category accelerates resolution and prevents extended downtime.

Permission and group membership issues

The most common post-installation problem involves docker group membership not taking effect. Symptoms include “permission denied” errors when running docker commands without sudo. Resolution requires:

# Verify group membership
groups ec2-user

# If docker group missing, add it
sudo usermod -aG docker ec2-user

# Force group refresh without logout
newgrp docker

# Test access
docker ps

Daemon startup failures

When the Docker daemon fails to start, examine the systemd journal for specific error messages:

# Check daemon status
sudo systemctl status docker

# View detailed logs
sudo journalctl -u docker.service -n 50

# Common fix for storage driver issues
sudo rm -rf /var/lib/docker
sudo systemctl start docker

Historical note: Earlier Docker versions on Amazon Linux occasionally conflicted with the default containerd installation. Modern packages resolve these dependencies automatically, but legacy instances may require manual containerd updates.

Network and registry connectivity

Image pull failures often indicate security group or DNS configuration problems. Verify outbound connectivity:

# Test registry connectivity
curl -I https://registry-1.docker.io/v2/

# Check DNS resolution
nslookup registry-1.docker.io

# Verify security group allows outbound 443
# (Check in AWS Console or via CLI)

With troubleshooting strategies established, you now have comprehensive knowledge to install, configure, and maintain Docker on EC2 instances across both Amazon Linux versions.

Conclusion

Installing Docker on an EC2 instance requires understanding the significant differences between Amazon Linux 2 and Amazon Linux 2023, from package management commands to security defaults. Amazon Linux 2023 represents the clear path forward, offering streamlined dnf-based installation, active long-term support, and modern security features like simplified rootless mode configuration. Teams still running AL2 must finalize their migration operations immediately given the June 30, 2026 end-of-life deadline, ensuring their container infrastructure remains supported and secure.

Production deployments benefit from the daemon.json configurations covered in this guide, particularly log rotation limits, the overlay2 storage driver, and live-restore capabilities. Security hardening through capability dropping, user namespace remapping, and inter-container communication restrictions transforms a basic Docker installation into enterprise-ready infrastructure. As container orchestration continues evolving with tools like Amazon ECS and EKS, the foundational Docker knowledge established here remains essential for understanding how containers execute regardless of the orchestration layer above them.