Skip to main content

Docker 25.0.14 (Amazon Linux 2023) AMI Administrator Guide

1. Quick Start Information​

Connection Methods:

  • Access the instance via SSH using the ec2-user user. Use sudo to run commands requiring root privileges. To switch to the root user, use sudo su - root.

Install Information:

  • OS: Amazon Linux 2023
  • Docker version: 25.0.14
  • Docker Compose version: Latest (Docker Compose Plugin)
  • Docker Buildx version: Latest (Docker Buildx Plugin)
  • Configuration File: /etc/docker/daemon.json

Docker Service Management:

  • Start Docker service: sudo systemctl start docker
  • Stop Docker service: sudo systemctl stop docker
  • Restart Docker service: sudo systemctl restart docker
  • Check Docker status: sudo systemctl status docker
  • Enable auto-start: sudo systemctl enable docker

Quick Verification Commands:

  • Check Docker version: docker --version
  • Check Compose version: docker compose version
  • List running containers: docker ps
  • List all containers: docker ps -a
  • List images: docker images
  • View Docker info: docker info

User Permissions:

  • The ec2-user is added to the docker group for sudo-free Docker commands
  • Important: Log out and log back in for group changes to take effect
  • Temporary activation (without re-login): newgrp docker

Firewall Configuration:

  • Please allow SSH port 22.
  • For Docker containers exposing services, open required ports in the security group.
  • For security, it is recommended to limit SSH access to trusted IPs only.

2. First Launch & Verification​

Step 1: Connect to Your Instance​

  1. Launch your instance in your cloud provider's console (e.g., AWS EC2)
  2. Ensure SSH port 22 is allowed in your security group
  3. Connect via SSH: 
    ssh -i your-key.pem ec2-user@YOUR_PUBLIC_IP

Step 2: Verify Docker Installation​

Check Docker version:

docker --version

Expected Output:

Docker version 25.0.14, build 0bab007

Check Docker Compose version:

docker compose version

Expected Output:

Docker Compose version v2.x.x

Check Docker Buildx version:

docker buildx version

Expected Output:

github.com/docker/buildx v0.x.x ...

Step 3: Verify Docker Service Status​

Check if Docker daemon is running:

sudo systemctl status docker

Expected Output:

● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: disabled)
     Active: active (running) since ...
   Main PID: xxxx (dockerd)

Step 4: Verify User Permissions​

Confirm ec2-user can run Docker without sudo:

docker ps

Expected Output:

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

No permission denied error means the group configuration is working correctly.

Step 5: Run a Test Container​

docker run --rm hello-world

Expected Output:

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

3. Architecture & Detailed Configuration​

This AMI uses Docker installed from the Amazon Linux 2023 built-in repository. Unlike Ubuntu-based setups that require adding the Docker official repository, Amazon Linux 2023 provides Docker packages directly through dnf, avoiding potential dependency conflicts.

Installation Architecture:

[Amazon Linux 2023 Built-in Repository]
         ↓
[docker 25.0.14]         → /usr/bin/docker
[docker-buildx-plugin]   → /usr/libexec/docker/cli-plugins/docker-buildx
[docker-compose-plugin]  → /usr/libexec/docker/cli-plugins/docker-compose
         ↓
[Systemd Service]
         ↓
docker.service → Auto-start on boot
         ↓
[User Group Configuration]
         ↓
ec2-user → docker group → no sudo required

Key Design Decisions:

  1. Built-in Repository: Amazon Linux 2023's dnf repo provides Docker 25.0.14 — no external repo needed, no dependency conflicts
  2. Plugin Architecture: Compose and Buildx are installed as CLI plugins (invoked via docker compose and docker buildx, not standalone binaries)
  3. User Group: ec2-user is pre-added to the docker group for seamless use
  4. Auto-Start: Docker service is enabled to start automatically on boot

Why Not Use the Docker Official Repository on Amazon Linux 2023?

ApproachAmazon Linux 2023 Built-inDocker Official Repo
CompatibilityFully tested with AL2023May cause conflicts
Dependency handlingManaged by AmazonRequires manual resolution
MaintenanceIntegrated with OS updatesSeparate update cycle
RecommendationPreferredNot recommended

3.1. Docker Configuration​

File Location: /etc/docker/daemon.json

If you need to customize Docker's behavior, create or edit this file:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

How This Works:

  • log-driver: json-file: Default log driver, stores logs as JSON
  • max-size: 100m: Rotates log file when it reaches 100 MB
  • max-file: 3: Keeps a maximum of 3 rotated log files

Apply changes after editing:

sudo systemctl restart docker

3.2. User Group Configuration​

File: /etc/group (managed by usermod)

The ec2-user is added to the docker group during AMI setup:

sudo usermod -aG docker ec2-user

How This Works:

  • usermod -aG docker: Appends the docker group to the user's group list
  • After this, the user can run Docker commands without sudo
  • The change takes effect after re-login or running newgrp docker

Verify group membership:

groups ec2-user

Expected Output:

ec2-user : ec2-user adm wheel systemd-journal docker

4. How-To-Create: Reproduce This Environment​

This section explains how this AMI was built, allowing you to reproduce the installation on any Amazon Linux 2023 system.

Step 1: Update the System​

Purpose: Ensure all packages are up to date before installing Docker.

sudo dnf update -y

How This Works:

  • dnf update -y: Updates all installed packages to their latest versions
  • Prevents conflicts between Docker and outdated system libraries
  • The -y flag auto-confirms all prompts

Step 2: Install Docker​

Purpose: Install Docker engine from the Amazon Linux 2023 built-in repository.

sudo dnf install -y docker

How This Works:

  • Uses Amazon Linux 2023's native package repository (no external repo needed)
  • Installs Docker 25.0.14 with all required dependencies
  • Automatically installs containerd as a dependency

Why Not Use the Docker Official Repository?

Adding the Docker official repository on Amazon Linux 2023 can cause dependency conflicts because AL2023 manages its own package versions with strict compatibility guarantees. The built-in docker package is specifically tested and maintained for AL2023.

Step 3: Install Docker Buildx Plugin​

Purpose: Enable multi-architecture image builds.

sudo dnf install -y docker-buildx-plugin

How This Works:

  • Installs the Buildx plugin to /usr/libexec/docker/cli-plugins/
  • Enables commands like docker buildx build --platform linux/amd64,linux/arm64
  • Required for building images targeting multiple CPU architectures

Step 4: Install Docker Compose Plugin​

Purpose: Enable multi-container orchestration with Docker Compose.

sudo dnf install -y docker-compose-plugin

How This Works:

  • Installs Docker Compose as a CLI plugin (not a standalone binary)
  • Invoked via docker compose (with space, not hyphen)
  • Supports docker-compose.yml files for defining multi-service applications

Step 5: Start and Enable Docker Service​

Purpose: Start Docker immediately and configure it to start on every boot.

sudo systemctl start docker
sudo systemctl enable docker

How This Works:

  • systemctl start docker: Starts the Docker daemon immediately
  • systemctl enable docker: Creates a systemd symlink so Docker starts on boot
  • For AMI images, enabling auto-start is essential so Docker is ready when the instance launches

Verify the service is running:

sudo systemctl status docker --no-pager

Step 6: Configure User Permissions​

Purpose: Allow ec2-user to run Docker commands without sudo.

sudo usermod -aG docker ec2-user
newgrp docker

How This Works:

  • usermod -aG docker ec2-user: Adds ec2-user to the docker Unix group
  • The docker group has permission to communicate with the Docker daemon socket (/var/run/docker.sock)
  • newgrp docker: Refreshes group membership in the current session without requiring re-login

Step 7: Verify Installation​

Purpose: Confirm everything is working correctly.

docker --version
docker run --rm hello-world
docker ps

Expected Results:

Docker version 25.0.14, build 0bab007

Hello from Docker!
This message shows that your installation appears to be working correctly.

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

5. Using the Docker Environment​

5.1. Basic Container Operations​

Run a container:

# Run interactively
docker run -it ubuntu bash

# Run in background (detached)
docker run -d nginx

# Run with port mapping
docker run -d -p 8080:80 nginx

# Run with auto-remove after exit
docker run --rm hello-world

Manage containers:

# List running containers
docker ps

# List all containers (including stopped)
docker ps -a

# Stop a container
docker stop CONTAINER_ID

# Remove a container
docker rm CONTAINER_ID

# View container logs
docker logs CONTAINER_ID

5.2. Image Management​

# List local images
docker images

# Pull an image
docker pull nginx:latest

# Remove an image
docker rmi nginx:latest

# Search Docker Hub
docker search nginx

5.3. Docker Compose​

Create a docker-compose.yml file:

version: '3.8'
services:
  web:
    image: nginx
    ports:
      - "80:80"
  db:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: example

Manage with Docker Compose:

# Start services
docker compose up -d

# View running services
docker compose ps

# View logs
docker compose logs

# Stop services
docker compose down

5.4. Docker Buildx (Multi-Architecture Builds)​

# Create a new builder
docker buildx create --use

# Build for multiple platforms
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .

# List available builders
docker buildx ls

5.5. System Maintenance​

# View disk usage
docker system df

# Remove stopped containers, unused networks, dangling images
docker system prune

# Remove all unused images (not just dangling)
docker system prune -a

# Remove unused volumes
docker volume prune

6. Important File Locations​

File PathPurpose
/usr/bin/dockerDocker CLI binary
/usr/bin/dockerdDocker daemon binary
/etc/docker/daemon.jsonDocker daemon configuration (create if needed)
/var/run/docker.sockDocker daemon Unix socket
/var/lib/docker/Docker data directory (images, containers, volumes)
/var/log/System logs (use journalctl -u docker for Docker logs)
/usr/libexec/docker/cli-plugins/docker-composeDocker Compose plugin
/usr/libexec/docker/cli-plugins/docker-buildxDocker Buildx plugin
/usr/lib/systemd/system/docker.serviceDocker systemd service file
/etc/groupUser group configuration (docker group)

7. Troubleshooting​

Issue 1: Permission Denied When Running Docker​

Symptoms:

$ docker ps
permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

Diagnosis:

Check if user is in docker group:

groups

Solution:

If docker is not listed in the output, add the user and refresh:

sudo usermod -aG docker ec2-user
newgrp docker

Or log out and log back in:

exit
ssh -i your-key.pem ec2-user@YOUR_PUBLIC_IP

Issue 2: Docker Service Not Starting​

Symptoms:

$ sudo systemctl start docker
Job for docker.service failed

Diagnosis:

View service logs:

sudo journalctl -u docker -n 50 --no-pager

Common Causes:

  1. Port conflict or socket already in use:
sudo lsof /var/run/docker.sock
  1. Invalid daemon.json configuration:
sudo dockerd --validate

Fix any syntax errors in /etc/docker/daemon.json, then restart:

sudo systemctl start docker

Issue 3: Docker Compose Command Not Found​

Symptoms:

$ docker compose version
docker: 'compose' is not a docker command.

Diagnosis:

Check if plugin is installed:

ls /usr/libexec/docker/cli-plugins/

Solution:

Reinstall the plugin:

sudo dnf install -y docker-compose-plugin

Issue 4: Cannot Pull Images (Network Issue)​

Symptoms:

$ docker pull nginx
Error response from daemon: Get "https://registry-1.docker.io/v2/": dial tcp: ...

Diagnosis:

Test internet connectivity:

curl -I https://registry-1.docker.io

Solution:

  1. Verify your EC2 instance has outbound internet access (check security group and VPC routing)
  2. If behind a proxy, configure Docker to use it by editing /etc/docker/daemon.json:
{
  "proxies": {
    "http-proxy": "http://proxy.example.com:8080",
    "https-proxy": "http://proxy.example.com:8080"
  }
}

Restart Docker after changes:

sudo systemctl restart docker

Issue 5: Disk Space Full (Docker Data)​

Symptoms:

Containers fail to start or images fail to pull due to insufficient disk space.

Diagnosis:

docker system df
df -h /var/lib/docker

Solution:

Remove unused Docker resources:

# Remove stopped containers, unused networks, dangling images
docker system prune -f

# Also remove unused images
docker system prune -a -f

# Remove unused volumes
docker volume prune -f

8. Final Notes​

Key Takeaways​

  1. Docker 25.0.14 installed from Amazon Linux 2023's native repository — no external repo needed
  2. Docker Compose Plugin enabled via docker compose command
  3. Docker Buildx Plugin included for multi-architecture builds
  4. ec2-user pre-configured in the docker group — no sudo required
  5. The installation is production-ready and AMI-optimized with auto-start enabled

Docker Use Cases​

  • Application Deployment: Package and run applications in isolated containers
  • Microservices: Run multiple services with Docker Compose
  • CI/CD Pipelines: Build, test, and deploy containerized applications
  • Multi-Architecture Builds: Build images for both x86_64 and ARM64 with Buildx
  • Development Environments: Consistent dev environments across teams

Amazon Linux 2023 vs Ubuntu for Docker​

AspectAmazon Linux 2023Ubuntu 24.04
Docker sourceBuilt-in dnf repoDocker official repo
AWS integrationNativeRequires configuration
Package managerdnfapt
SSH userec2-userubuntu
Docker version25.0.1429.x (latest CE)

Additional Resources​

For support or questions, please contact the Easycloud team.