thelinuxvault blog

Installing Docker on CentOS 9 Stream: A Comprehensive Guide

Docker has revolutionized software development and deployment by enabling containerization—an efficient way to package applications with their dependencies into lightweight, portable units called containers. Containers ensure consistency across environments, simplify deployment, and optimize resource usage, making them a staple in modern DevOps and cloud workflows.

CentOS 9 Stream, a rolling-release Linux distribution from Red Hat, offers cutting-edge features and stability, making it an excellent choice for running Docker. This guide will walk you through step-by-step instructions to install Docker on CentOS 9 Stream, configure it for optimal use, troubleshoot common issues, and even uninstall it if needed. By the end, you’ll have a fully functional Docker environment ready to deploy your applications.

2026-02

Table of Contents#

  1. Prerequisites
  2. Installing Docker Engine
  3. Post-Installation Steps
  4. Configuring Docker (Optional)
  5. Troubleshooting Common Issues
  6. Uninstalling Docker
  7. Conclusion
  8. References

Prerequisites#

Before starting, ensure your system meets the following requirements:

  • A running instance of CentOS 9 Stream (physical, virtual machine, or cloud instance).
  • A user account with sudo privileges (to execute administrative commands).
  • An active internet connection (to download Docker packages and dependencies).
  • Basic familiarity with Linux command-line operations.

Installing Docker Engine#

Docker provides official packages for CentOS via its dedicated repository. Follow these steps to install Docker Engine, the core component for running containers.

Step 1: Update System Packages#

First, update your system’s package index to ensure you have the latest versions of existing packages:

sudo dnf update -y

The -y flag automatically confirms prompts to avoid manual intervention.

Step 2: Install Required Dependencies#

Docker requires a few dependencies to configure its repository and handle HTTPS connections. Install them with:

sudo dnf install -y dnf-plugins-core ca-certificates curl software-properties-common
  • dnf-plugins-core: Adds repository management capabilities to dnf.
  • ca-certificates: Ensures secure HTTPS connections by verifying SSL certificates.
  • curl: Used to download files from the internet (e.g., Docker’s GPG key).
  • software-properties-common: Helps manage system repositories.

Step 3: Add Docker’s Official Repository#

To install Docker, you’ll need to add Docker’s official repository to your system. This ensures you get the latest stable releases directly from Docker.

Add Docker’s GPG Key#

First, import Docker’s official GPG key to verify package integrity:

curl -fsSL https://download.docker.com/linux/centos/gpg | sudo gpg --dearmor -o /etc/pki/rpm-gpg/RPM-GPG-KEY-docker
  • curl -fsSL: Downloads the GPG key silently (-s), follows redirects (-L), and fails quietly (-f).
  • gpg --dearmor: Converts the ASCII key to a binary .gpg file for dnf to use.

Add the Docker Repository#

Next, add the Docker stable repository to your system:

sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

Verify the repository was added with:

dnf repolist enabled | grep docker-ce

You should see output like:

docker-ce-stable    Docker CE Stable - x86_64

Step 4: Install Docker Engine#

Now install Docker Engine, containerd (the container runtime), and Docker CLI:

sudo dnf install -y docker-ce docker-ce-cli containerd.io
  • docker-ce: Docker Community Edition (free, open-source).
  • docker-ce-cli: Command-line interface for Docker.
  • containerd.io: Container runtime (manages low-level container operations).

If prompted to accept the GPG key, type y and press Enter.

Step 5: Start and Enable Docker Service#

Docker runs as a systemd service. Start the service and enable it to launch on boot:

sudo systemctl start docker   # Start Docker immediately
sudo systemctl enable docker  # Enable Docker to start on boot

Verify Docker is running:

sudo systemctl status docker

You should see output indicating the service is active (running):

● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; vendor preset: disabled)
     Active: active (running) since Wed 2024-05-20 12:34:56 UTC; 1min ago
       Docs: https://docs.docker.com
   Main PID: 12345 (dockerd)
      Tasks: 8
     Memory: 45.6M
        CPU: 345ms
     CGroup: /system.slice/docker.service
             └─12345 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

Step 6: Verify Docker Installation#

To confirm Docker is working, run the official hello-world container:

sudo docker run hello-world

This command downloads a lightweight test image, runs a container, and prints a success message:

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

If you see this output, Docker is installed and functioning properly!

Post-Installation Steps#

By default, Docker requires sudo privileges to run commands (e.g., sudo docker run ...). To avoid typing sudo every time, add your user to the docker group.

The docker group is created during installation. Users in this group can run Docker commands without sudo.

Add your user to the docker group:

sudo usermod -aG docker $USER
  • -aG docker: Appends (-a) the user to the docker group (-G).
  • $USER: Variable representing the current logged-in user.

Apply Group Changes#

Group changes require a logout/login to take effect. Verify your user is in the docker group with:

groups  # After logging out and back in

You should see docker in the list of groups.

Test Docker without sudo:

docker run hello-world

If successful, you’ll see the same "Hello from Docker!" message as before.

Configuring Docker (Optional)#

Customizing the Docker Daemon#

The Docker daemon (dockerd) uses a configuration file (/etc/docker/daemon.json) to set advanced options (e.g., storage drivers, network settings, or log limits).

Example: Limit Log Size#

To prevent Docker logs from consuming excessive disk space, add log rotation settings:

sudo mkdir -p /etc/docker  # Create directory if it doesn’t exist
sudo nano /etc/docker/daemon.json

Add the following content:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",    # Max log size per container (10MB)
    "max-file": "3"       # Max log files to retain
  }
}

Save the file and restart Docker to apply changes:

sudo systemctl restart docker

Setting Up Docker Compose#

Docker Compose is a tool for defining and running multi-container Docker applications (e.g., a web app + database). Install it with:

Download Docker Compose#

Check the latest release and replace v2.24.6 with the current version:

DOCKER_COMPOSE_VERSION="v2.24.6"
sudo curl -SL https://github.com/docker/compose/releases/download/${DOCKER_COMPOSE_VERSION}/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose

Make It Executable#

sudo chmod +x /usr/local/bin/docker-compose

Verify Installation#

docker-compose --version

Output: Docker Compose version v2.24.6

Troubleshooting Common Issues#

Docker Fails to Start#

If Docker doesn’t start, check the service status and logs:

sudo systemctl status docker  # Check status
sudo journalctl -xeu docker   # View detailed logs

Common fixes:

  • Ensure no other container runtimes (e.g., Podman) conflict with Docker. Uninstall Podman if needed: 
    sudo dnf remove -y podman
  • Verify the daemon.json file has valid JSON syntax (use jsonlint to check).

Permission Denied (Non-Root Users)#

If you get a "permission denied" error when running Docker without sudo:

  • Ensure your user is in the docker group (see Post-Installation Steps).
  • Restart the Docker service: 
    sudo systemctl restart docker
  • Log out and back in to apply group changes.

Firewall Blocking Docker Traffic#

Docker uses bridge networks to connect containers. If containers can’t communicate, check the firewall:

Allow Docker Bridge Traffic#

sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0
sudo firewall-cmd --reload
  • docker0: Default Docker bridge interface.
  • trusted zone: Allows unrestricted traffic on the interface.

Uninstalling Docker#

To remove Docker and related components:

Step 1: Uninstall Docker Packages#

sudo dnf remove -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Step 2: Delete Docker Data#

Remove containers, images, volumes, and configuration files (this deletes all Docker data!):

sudo rm -rf /var/lib/docker   # Docker data (images, containers, volumes)
sudo rm -rf /var/lib/containerd  # containerd data
sudo rm -rf /etc/docker      # Configuration files

Conclusion#

You’ve successfully installed Docker on CentOS 9 Stream! You now have a powerful containerization platform to build, ship, and run applications. Next steps include exploring Docker Compose for multi-container apps, learning about Docker Swarm or Kubernetes for orchestration, or diving into container security best practices.

References#