Installing Docker and Configuring the Environment

Installing Docker is easier than you might think—whether you're using Windows, Mac, or Linux, you can have a fully functional container environment up and running in 10 minutes.

1. What You'll Learn

• How to Install Docker on Various Platforms
• The Difference Between Docker Desktop and Docker Engine
• Mirror Accelerator Configuration
• Running Docker as a non-root user
• Docker Context Management

2. A True Story of a Team’s Technical Lead

(1) Challenge: The 15 individuals have different circumstances

Charlie's team had just decided to fully adopt Docker, but Lisa, a new team member, asked, "Should I install Docker Desktop or Docker Engine? Is the installation process the same on Mac and Linux?" The 15-person team used four different operating systems (Windows, Mac, Ubuntu, and CentOS), and the installation process varied for each one; just setting up the environment took two days.

(2) Implementing the Decision Tree Algorithm

Charlie drew an installation decision tree—3 OS types × 2 modes—and got the team up and running in 15 minutes.

# Verify Docker installation after setup
docker run hello-world

(3) Benefits: A unified, frictionless environment

After the team completed the unified installation, everyone’s docker version output became consistent, and the number of environment-related issues dropped from 5 per week to 0.

3. Docker Desktop vs Docker Engine

Before installing Docker, make sure you understand the differences between the two distributions.

graph TB
    START["Select Docker Version"] --> OS{"Your operating system？"}
    OS -->|Windows / Mac| DT["Docker Desktop<br/>with GUI + VM + CLI"]
    OS -->|Linux Server| DE["Docker Engine<br/>Pure CLI Services"]
    DT --> DEV["✅ Recommended Development Environments"]
    DE --> PROD["✅ Recommended Production Environments"]

graph TB
    START["Select Docker Version"] --> OS{"Your operating system？"}
    OS -->|Windows / Mac| DT["Docker Desktop<br/>with GUI + VM + CLI"]
    OS -->|Linux Server| DE["Docker Engine<br/>Pure CLI Services"]
    DT --> DEV["✅ Recommended Development Environments"]
    DE --> PROD["✅ Recommended Production Environments"]

(1) Comparison of the Two Distributions

(2) Installation Decision-Making Process

4. Installation Instructions for Each Platform

(1) Windows Installation

Prerequisites:

• Windows 10 64-bit (version 1903 or later) or Windows 11
• Enable WSL2 (Windows Subsystem for Linux 2)
• Enable Hyper-V (optional; WSL2 mode is recommended)

Installation Steps:

(2) Mac Installation

(3) Linux Installation (Ubuntu/Debian)

# 1. Update package index
sudo apt-get update

# 2. Install prerequisites
sudo apt-get install -y ca-certificates curl gnupg

# 3. 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

# 4. Add Docker repository
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

# 5. Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 6. Start Docker
sudo systemctl start docker
sudo systemctl enable docker

# 7. Verify
sudo docker run hello-world

5. Configuration for Non-Root Users

By default, only the root user and members of the docker group can run Docker on Linux.

▶ Example: Add the current user to the docker group (Difficulty: ⭐)

# Add current user to docker group
sudo usermod -aG docker $USER

# Apply group change (or log out and back in)
newgrp docker

# Verify: run docker without sudo
docker run hello-world

6. Mirror Accelerator Configuration

Accessing Docker Hub from within China can be slow, but configuring an image accelerator can significantly improve pull speeds.

(1) Popular Mirror Accelerators

▶ Example: Configuring a Mirror Accelerator on Linux (Difficulty: ⭐⭐)

# Create or edit Docker daemon configuration
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}
EOF

# Restart Docker to apply changes
sudo systemctl daemon-reload
sudo systemctl restart docker

# Verify the configuration
docker info | grep -A 5 "Registry Mirrors"

Registry Mirrors:
  https://docker.mirrors.ustc.edu.cn/
  https://hub-mirror.c.163.com/

▶ Example: Configuring the Docker Desktop Image Accelerator (Difficulty: ⭐)

To configure in the Docker Desktop GUI: Settings → Docker Engine → Add the registry-mirrors array to the JSON → Apply & Restart.

Or edit the configuration file directly (Mac: ~/.docker/daemon.json, Windows: C:\Users\<user>\.docker\daemon.json).

7. Docker Context Management

Docker contexts allow you to quickly switch between multiple Docker hosts—such as your local Docker instance and a remote server.

▶ Example: Viewing and Switching Docker Contexts (Difficulty: ⭐⭐)

# List all Docker contexts
docker context ls

NAME                TYPE                DESCRIPTION
default *           moby                Current DOCKER_HOST based configuration
remote-server       moby                Remote Docker on 10.0.1.100

# Create a new context for a remote Docker host
docker context create remote-server --docker "host=ssh://user@10.0.1.100"

# Switch to the remote context
docker context use remote-server

# Verify: now all docker commands run on the remote server
docker ps

# Switch back to local
docker context use default

▶ Example: Verifying Successful Installation (Difficulty: ⭐)

# Full verification checklist
docker version          # Client + Server versions
docker info             # System-wide info
docker run hello-world  # End-to-end test

8. Troubleshooting Common Installation Issues

9. Complete Example: Setting Up a Docker Environment on an Ubuntu Server from Scratch

# ============================================
# Complete walkthrough: Install Docker on Ubuntu
# Covers: install, sudo-free, mirror, verify
# ============================================

# 1. Install Docker Engine
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
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
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
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 2. Start and enable Docker service
sudo systemctl start docker
sudo systemctl enable docker

# 3. Add current user to docker group (no more sudo)
sudo usermod -aG docker $USER
newgrp docker

# 4. Configure registry mirror for faster pulls
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn"
  ]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

# 5. Verify: run Nginx and access it
docker run -d -p 8080:80 --name test-nginx nginx:latest
curl http://localhost:8080

# 6. Clean up
docker stop test-nginx
docker rm test-nginx

# docker run -d -p 8080:80 --name test-nginx nginx:latest
a1b2c3d4e5f6...

# curl http://localhost:8080
<!DOCTYPE html>
<html><head><title>Welcome to nginx!</title>...

❓ FAQ

📖 Summary

• Docker Desktop is suitable for development on Windows and Mac (with a GUI), while Docker Engine is suitable for Linux servers (CLI only)
• For Windows, use WSL2 mode; for Mac, select the appropriate version based on whether your system uses Intel or Apple Silicon
• Use the official APT/YUM repositories for Linux installation; do not use the outdated versions that come with the system.
• Adding a user to the docker group allows them to run Docker without using sudo
• Configure a mirror accelerator to resolve slow access to Docker Hub within China
• Docker Context allows you to quickly switch between local and remote Docker hosts

📝 Exercises

1. Basic Problem (Difficulty: ⭐): Install Docker on your local machine, run docker run hello-world, and take a screenshot of the output to save it.
2. Advanced Exercise (Difficulty: ⭐⭐): Set up a domestic mirror accelerator and run docker info | grep -A 5 "Registry Mirrors" to verify that the configuration is working.
3. Challenge (Difficulty: ⭐⭐⭐): Run docker run -d -p 8080:80 nginx to start Nginx, use a browser to visit http://localhost:8080 to verify that the page displays correctly, and then use docker stop and docker rm to clean up the containers.

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us