AI VOID
DATE: 2026.05.22 00:00 CLEARANCE: PUBLIC

Project Setup and Docker Engine Installation

Docker Docker Engine Containerization Development Setup WSL2

// table of contents

▼

Embarking on a journey to build a production-ready application stack requires a solid foundation. This first chapter focuses on establishing that foundation: setting up your local development environment and installing Docker Engine. This crucial step enables you to run, build, and manage containers, which are the atomic units of modern cloud-native applications.

By the end of this chapter, you will have a fully functional Docker Engine installation on your system, verified and ready to execute your first container. This ensures consistency and reproducibility from your local machine to future deployment environments.

Project Overview: Building a Production-Ready Docker Stack

Our overarching project aims to build a fully functional, multi-service web application stack deployed using Docker Compose. This guide will walk you through key production-ready practices, including image optimization, secure data persistence, health checks, and basic scaling. The target audience includes developers and DevOps engineers who want to deploy robust applications using Docker. Success means having a deployable, resilient, and observable application stack.

Tech Stack at a Glance

For this project, our primary tools are:

  • Docker Engine: The core runtime for creating and managing containers.
  • Docker Compose: A tool for defining and running multi-container Docker applications.

Version Information (Checked 2026-05-22):

  • Docker Engine: The exact stable version of Docker Engine is continuously updated. We will always recommend installing the latest stable release available via official channels. The installation instructions below are geared towards this.
  • Docker Compose: We will leverage the docker compose CLI plugin, which adheres to the Compose Specification. This modern approach means we generally avoid specifying a version field in docker-compose.yml files, letting the Compose CLI automatically use the latest specification.

Build Plan: Chapter 1 Milestones

This chapter is entirely dedicated to setting up your local Docker environment. Specifically, we will:

  1. Install Docker Engine: Install the core Docker daemon and CLI on your chosen operating system.
  2. Verify Installation: Confirm that Docker Engine is running and accessible by executing a test container.

Core Concept: Understanding Docker Engine

At its heart, Docker Engine is a client-server application that consists of three main components:

  1. Docker Daemon (dockerd): A persistent background process that manages Docker objects like images, containers, networks, and volumes. It listens for Docker API requests.
  2. Docker REST API: An interface that programs can use to talk to the daemon and instruct it on what to do.
  3. Docker CLI (Command Line Interface): The docker command you’ll use in your terminal to interact with the Docker daemon via the API.

Why Docker Engine exists: It provides a consistent environment to package and run applications. By isolating applications into containers, Docker solves the “it works on my machine” problem, ensuring that an application behaves the same way regardless of the underlying infrastructure. This isolation also enhances security and resource management.

Planning the Docker Engine Installation

A successful Docker Engine installation is the non-negotiable first step. It ensures that the docker command is available, the daemon is active, and your user has the necessary permissions to interact with it.

Prerequisites

Before you start, ensure your system meets these basic requirements:

  • Operating System: A recent, stable version of Linux (e.g., Ubuntu, Debian), macOS, or Windows 10/11.
  • Text Editor: Visual Studio Code, Sublime Text, or similar, for future code editing.
  • Command-Line Proficiency: Basic familiarity with running commands in a terminal or PowerShell.
  • Internet Connection: Essential for downloading Docker packages and images.

The installation approach differs significantly based on your operating system. For Linux, we’ll install directly from Docker’s official repositories. For macOS and Windows, the recommended path is Docker Desktop, which bundles Docker Engine, Docker Compose, and other utilities.

Step-by-Step Docker Engine Installation

Follow the instructions below for your specific operating system. Always prioritize the official Docker documentation for the most up-to-date and architecture-specific instructions.

🧠 Important: The steps provided below are general guidelines as of 2026-05-22. For the most precise and current installation instructions, always refer to the official Docker documentation for your specific OS and architecture.

1. For Linux (Ubuntu/Debian Example)

Installing Docker Engine on Linux from its official repositories is the preferred method for stability and updates.

  1. Uninstall Older Versions (if present): Ensure a clean slate by removing any existing or conflicting Docker packages.

    for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt remove $pkg; done

  2. Set Up Docker’s Official Repository: This involves installing necessary utility packages, adding Docker’s GPG key for package verification, and then configuring the stable repository.

    # Update package index and install prerequisites
sudo apt update
sudo apt install ca-certificates curl gnupg lsb-release -y

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the Docker repository to Apt sources
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update the package index again to include Docker packages
sudo apt update

  3. Install Docker Engine Components: Install the Docker Engine, CLI, and the containerd.io runtime, along with the docker-buildx-plugin and docker-compose-plugin.

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

  4. Add Your User to the docker Group: This is a critical step to run Docker commands without prepending sudo. After running this command, you must log out and log back in (or reboot your system) for the changes to take effect.

    sudo usermod -aG docker $USER

    ⚡ Quick Note: Simply opening a new terminal might not be sufficient. A full re-login ensures your user’s group memberships are correctly re-evaluated.

2. For macOS and Windows (using Docker Desktop)

For macOS and Windows environments, Docker Desktop is the recommended and most straightforward solution. It bundles Docker Engine, Docker Compose, Kubernetes, and other developer tools into a single, easy-to-manage application.

  1. Download Docker Desktop: Navigate to the official Docker Desktop download page: https://docs.docker.com/desktop/install/ Download the installer appropriate for your operating system.

  2. Install Docker Desktop:

    • macOS: Open the downloaded .dmg file and drag the Docker icon into your Applications folder. Launch Docker Desktop from Applications.
    • Windows: Run the downloaded Docker Desktop Installer.exe. Follow the on-screen instructions. Crucially, ensure “Use WSL 2 based engine” is enabled during installation if you are on Windows, as it offers superior performance and compatibility for Linux containers.

  3. Windows Specific - Enable WSL2 (if needed): Docker Desktop on Windows relies on Windows Subsystem for Linux 2 (WSL2). If you haven’t already, enable and update WSL2:

    • Open PowerShell as an Administrator and run:
      wsl --install
wsl --update
wsl --set-default-version 2
    • You may also need to install a Linux distribution (e.g., Ubuntu) from the Microsoft Store if you don’t have one already, and then run wsl --set-default-version 2 again after the distribution is installed.

  4. Start Docker Desktop: Launch Docker Desktop from your Applications (macOS) or Start Menu (Windows). It will start the Docker Engine in the background. Wait for the Docker icon in your system tray (Windows) or menu bar (macOS) to indicate that Docker Engine is running and ready.

Verification: Confirming Your Setup

After installation, it’s vital to confirm Docker Engine is correctly installed and operational.

  1. Check Docker Version: Open your terminal or command prompt and execute these commands:

    docker --version
docker compose version

    You should see output similar to this, confirming the Docker CLI and Compose CLI are installed:

    Docker version 25.0.3, build 4de43a0
Docker Compose version v2.24.5

    (Note: The specific version numbers will vary depending on the latest stable release at the time of your installation.)

  2. Run a Test Container: The most definitive way to verify the Docker Engine daemon is running and responsive is to run the official hello-world image.

    docker run hello-world

    Expected Output: A successful execution will display output similar to this:

    Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
... (download progress) ...
Digest: sha256:f5233545e43561888496a7989027956529ce578fe166c36dc2b11617a69b406b
Status: Downloaded newer image for hello-world:latest

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

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output back to the Docker client, which sent it to your terminal.

    This message signifies that Docker Engine is fully operational, capable of pulling images, creating containers, and executing commands within them.

Production Awareness: Beyond Development Setup

While this chapter focuses on your local development environment, it’s important to briefly touch upon production considerations related to Docker Engine:

  • Host Security: The underlying operating system running Docker Engine (the “Docker host”) is a critical attack surface. Secure it by limiting access, regularly patching, and following least-privilege principles. In production, tools like docker-bench-security can audit your Docker host and container configurations for common vulnerabilities.
  • User Permissions: Granting a user access to the docker group (allowing docker commands without sudo) is convenient for development but bestows root-level privileges over the host. In production, this practice is generally avoided. Instead, orchestration platforms (like Kubernetes) or dedicated CI/CD systems interact with the Docker daemon with appropriate permissions.
  • Resource Management: Docker Engine and its containers consume system resources (CPU, memory, disk I/O). On a development machine, ensure you have sufficient resources to avoid performance bottlenecks. In production, careful resource allocation and monitoring are essential for stability and performance.

Troubleshooting Common Issues

Encountering issues during installation is common. Here are some frequent problems and their solutions:

  1. docker: command not found:

    • Cause: The Docker CLI might not be installed correctly, or its executable path isn’t included in your system’s PATH environment variable. On Linux, this often means the installation process failed or was incomplete.
    • Solution: For Linux, meticulously re-follow the installation steps, paying close attention to repository setup. For macOS/Windows, ensure Docker Desktop is installed and running, and that its bin directory is in your system’s PATH (Docker Desktop usually handles this automatically).

  2. Got permission denied while trying to connect to the Docker daemon socket (Linux only):

    • Cause: Your user account is not a member of the docker group, or the group membership hasn’t been activated since you added it.
    • Solution: Verify you ran sudo usermod -aG docker $USER. Then, critically, log out and log back in to your user session (or reboot your machine). A simple newgrp docker might work for the current terminal but is less reliable for a permanent fix.

  3. Docker Desktop not starting / WSL2 issues (Windows only):

    • Cause: WSL2 might not be properly installed, updated, or enabled on your Windows system, or there could be a conflict with virtualization settings in your BIOS/UEFI.
    • Solution: Ensure WSL2 is fully installed and updated by running wsl --update and wsl --set-default-version 2 in an administrative PowerShell. Check your BIOS/UEFI settings to confirm hardware virtualization (e.g., Intel VT-x or AMD-V) is enabled. Consult the official Docker Desktop troubleshooting guide for specific error messages or advanced diagnostics.

Summary & Next Step

Congratulations! You have successfully installed Docker Engine and verified its functionality by running your first container. This foundational environment setup is now complete, equipping your machine for containerized application development.

Key Takeaways:

  • Docker Engine is the indispensable core for building and running containers.
  • Installation methods are OS-specific, with official documentation being the most reliable source for current versions.
  • Correct user permissions (especially on Linux) and proper WSL2 setup (on Windows) are crucial for smooth operation.
  • Running the hello-world container is the quickest and most effective way to confirm your Docker setup is working.

With Docker Engine ready, we are now prepared to containerize our first application. In the next chapter, we will take a simple web application and package it into a Docker image, laying the groundwork for our multi-service deployment.

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.

References