Say Hi

Step By Step Guide to Installing Docker on Linux

2024-09-11

Install Docker on Ubuntu/Debian or CentOS/RHEL, configure it to run without sudo, and troubleshoot common permission issues. This guide covers the complete installation process and essential Docker container management commands.

Docker is a containerization platform that allows you to package applications and their dependencies into lightweight, portable containers. Whether you're a developer looking to containerize your applications or a system administrator managing server deployments, Docker has become an essential tool in modern software development and deployment workflows.

This guide will walk you through installing Docker on the most popular Linux distributions and help you resolve common issues you might encounter during setup and usage.

Prerequisites

Before we start, make sure you have:

  1. A Linux system running Ubuntu/Debian or CentOS/RHEL
  2. Root or sudo access
  3. Basic understanding of command line operations
  4. Internet connection for downloading packages

Installing Docker on Ubuntu/Debian

Ubuntu and Debian use the APT package manager, making Docker installation straightforward. Here's the step-by-step process:

Step 1: Update Existing Packages

First, ensure your system is up to date with the latest package information and security updates:

sudo apt update
sudo apt upgrade -y

Step 2: Install Dependencies

Docker requires several system dependencies to function properly. Install these essential packages:

sudo apt install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

These packages provide:

  • ca-certificates: SSL certificate authorities for secure connections
  • curl: Tool for downloading files from the internet
  • gnupg: GNU Privacy Guard for verifying signatures
  • lsb-release: Linux Standard Base release information

Step 3: Add Docker's Official GPG Key

Security is crucial when adding external repositories. Add Docker's GPG key to verify package authenticity:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Step 4: Set Up the Repository

Add the official Docker repository to your system's package sources:

echo \
  "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Step 5: Install Docker Engine

Now install Docker and its components:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

This installs:

  • docker-ce: Docker Community Edition engine
  • docker-ce-cli: Command-line interface
  • containerd.io: Container runtime
  • docker-buildx-plugin: Extended build capabilities
  • docker-compose-plugin: Multi-container application management

Step 6: Start and Enable Docker

Configure Docker to start automatically on system boot:

sudo systemctl start docker
sudo systemctl enable docker

Step 7: Verify Installation

Test that Docker is working correctly:

docker --version
docker run hello-world

The hello-world container will download and run a simple test application to confirm everything is working.

Installing Docker on CentOS/RHEL

CentOS and Red Hat Enterprise Linux use YUM/DNF package managers. The installation process is slightly different but equally straightforward.

Step 1: Remove Older Docker Versions

Clean up any existing Docker installations that might conflict:

sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine

Step 2: Install Required Packages

Install the utilities needed for repository management:

sudo yum install -y yum-utils

Step 3: Add Docker Repository

Add the official Docker repository:

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

Step 4: Install Docker Engine

Install Docker and its components:

sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Step 5: Start and Enable Docker

Start the Docker service and enable it for automatic startup:

sudo systemctl start docker
sudo systemctl enable docker

Step 6: Verify Installation

Confirm Docker is working properly:

docker --version
docker run hello-world

Running Docker as Non-Root User

By default, Docker requires root privileges. To use Docker without sudo, add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

After running these commands, you can use Docker commands without sudo. The newgrp command applies the group change immediately without requiring a logout.

Troubleshooting: Permission Denied Error

One of the most common issues new Docker users encounter is the permission denied error. If you see this message:

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

This means your user doesn't have permission to communicate with the Docker daemon because it's not part of the docker group.

The Solution

The error occurs because Docker runs as root and creates a socket file that regular users cannot access. Here's how to fix it:

Step 1: Add Your User to the Docker Group

Run this command to add your current user to the docker group:

sudo usermod -aG docker $USER

The -aG flag appends the group to the user without removing existing groups, and $USER automatically refers to your current username.

Step 2: Apply the Group Change

You have two options to apply the group membership:

Option A: Log out and log back in This is the cleanest way to ensure all group changes take effect system-wide.

Option B: Use the newgrp command If you don't want to log out, use:

newgrp docker

This applies the group membership for your current shell session only.

Step 3: Test the Fix

Try running Docker again:

docker run hello-world

The permission error should now be resolved.

Essential Docker Container Management

Once Docker is working correctly, you'll need to know how to manage your containers effectively. Here are the essential commands for stopping, removing, and rebuilding containers:

Viewing Running Containers

To see all currently running containers:

docker ps

For all containers (including stopped ones):

docker ps -a

Stopping and Removing Containers

When you need to stop a running container:

docker stop <container_id_or_name>

To remove a stopped container:

docker rm <container_id_or_name>

Managing Docker Images

List all images on your system:

docker images

Remove an unused image:

docker rmi <image_id_or_name>

Complete Rebuild Process

When you need to completely rebuild your application container:

  1. Stop the running container:

    docker stop my-app-container

  2. Remove the container:

    docker rm my-app-container

  3. Remove the old image (optional):

    docker rmi my-app-image

  4. Rebuild the image:

    docker build -t my-app-image .

  5. Run the new container:

    docker run -d -p 3000:3000 --name my-app-container my-app-image

Quick Cleanup Commands

For a complete cleanup and rebuild in one go:

docker stop my-app-container
docker rm my-app-container
docker rmi my-app-image
docker build -t my-app-image .
docker run -d -p 3000:3000 --name my-app-container my-app-image

Replace my-app-container, my-app-image, and port numbers with your actual values.

Best Practices

  1. Keep Docker updated: Regularly update Docker to get the latest security patches and features
  2. Use specific image tags: Avoid using 'latest' tags in production environments
  3. Clean up regularly: Remove unused containers and images to save disk space
  4. Use .dockerignore: Exclude unnecessary files from your build context
  5. Monitor resource usage: Keep an eye on container resource consumption
  6. Use multi-stage builds: Optimize image size by using multi-stage Dockerfiles

Common Issues and Solutions

Issue: Docker daemon not starting

  • Check if the service is enabled: sudo systemctl status docker
  • Try restarting: sudo systemctl restart docker

Issue: Out of disk space

  • Clean up unused containers: docker container prune
  • Remove unused images: docker image prune
  • Clean everything: docker system prune -a

Issue: Port already in use

  • Check what's using the port: sudo netstat -tulpn | grep :3000
  • Use a different port mapping: -p 3001:3000

Conclusion

You now have Docker installed and configured on your Linux system! This powerful containerization platform will help you develop, deploy, and manage applications more efficiently. The troubleshooting steps covered here should resolve the most common issues you might encounter.

Remember to regularly update Docker and clean up unused resources to maintain optimal performance. As you become more comfortable with Docker, explore advanced features like Docker Compose for multi-container applications, Docker Swarm for orchestration, and container optimization techniques.

Docker's ecosystem is vast and constantly evolving, so don't hesitate to consult the official documentation for the latest features and best practices. Happy containerizing!

Back to all posts