Docker Desktop Setup: Install, Configure, and Fix Like a Pro

Docker Desktop is the single biggest source of 'it works on my machine' problems I've seen in 15 years. Not because it's bad — because people install it, click 'Next', and never touch the settings. Then at 2 AM, their container eats 16GB of RAM and the laptop freezes. I've debugged that exact scenario three times this year alone.

The problem Docker Desktop solves is real: you need a consistent environment to run Linux containers on Windows or Mac without a full VM. Before Docker Desktop, we hacked together Vagrant boxes and prayed. Now you get a one-click install that handles the VM, networking, and file sharing. But that convenience comes with hidden defaults that will betray you in production.

By the end of this, you'll install Docker Desktop correctly, configure resource limits so your laptop doesn't melt, and fix the three most common failures that send junior devs to Stack Overflow. No fluff. Just the stuff that actually breaks.

Why Docker Desktop Exists — The VM You Didn't Know You Needed

Docker containers are Linux-native. They use Linux kernel features like cgroups and namespaces. Windows and Mac don't have those kernels. So Docker Desktop runs a lightweight Linux VM (Hyper-V on Windows, HyperKit on Mac) that hosts the Docker Engine. The GUI is just a friendly wrapper around that VM.

Without Docker Desktop, you'd need to install a full Linux VM, install Docker inside it, and manage port forwarding manually. Docker Desktop automates all that. But the VM is still there — it consumes CPU, RAM, and disk. And its default settings are tuned for 'works on my machine', not 'survives a production load test'.

The first thing you must do after install: open the settings and set resource limits. Don't trust the defaults.

// io.thecodeforge — DevOps tutorial

# Check Docker Desktop resource usage from command line
docker info | grep -i memory
# Output: Total Memory: 1.944GiB (default 2GB)

# Check disk usage
docker system df
# Output: Type            Total     Active   Size     Recycled
#        Images          5         2        1.234GB  0B
#        Containers      3         1        45.6MB   0B
#        Local Volumes   2         1        2.1GB    0B
#        Build Cache     0         0        0B       0B

# To see actual VM resource allocation (Windows WSL2):
wsl --status
# Output: Default Distribution: docker-desktop
#         Default Version: 2
#         Memory: 2GB (limit set by Docker Desktop)

Installation — The Right Way, Once

Download from docker.com. Not a package manager. Not a random blog link. The official site.

On Windows: you need WSL2. Install it first. Open PowerShell as admin and run wsl --install. Then reboot. During Docker Desktop install, check 'Use WSL 2 instead of Hyper-V'. This gives better performance and integration with Windows filesystem.

On Mac: choose the Intel or Apple Silicon chip version. Apple Silicon (M1/M2) users must install Rosetta 2 for some legacy containers: softwareupdate --install-rosetta. Without it, containers built for x86 will crash with 'exec format error'.

After install, open Docker Desktop. It will start the VM. This takes 30-60 seconds. Don't panic. Run docker run hello-world to verify. If you see 'Hello from Docker!', you're good.

// io.thecodeforge — DevOps tutorial

# Verify Docker CLI works
docker --version
# Output: Docker version 24.0.6, build ed223bc

# Run hello-world container
docker run hello-world

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

# Check Docker Desktop is running (GUI)
# Open Docker Desktop -> should show green 'Docker Desktop is running' in bottom left

Configuration — Stop the Defaults from Sabotaging You

Open Docker Desktop settings. Click the gear icon. Go to Resources > Advanced. Set Memory to at least 4GB. Set CPUs to 4. Set Swap to 1GB. Set Disk image size to at least 64GB. These are the minimums for a multi-container dev environment.

Why these numbers? Your database container alone needs 1-2GB. Your app container needs 512MB-1GB. Add a cache like Redis (256MB). You're at 2.5GB before you start. The default 2GB guarantees OOM kills.

Go to Resources > File Sharing. Add the drives you'll mount into containers. On Windows, avoid mounting the entire C: drive — it slows everything down. Mount only your project folders.

Go to Docker Engine. This is the daemon config JSON. Add "log-driver": "json-file" and "log-opts": {"max-size": "10m", "max-file": "3"}. This prevents logs from filling your disk — a classic rookie mistake.

// io.thecodeforge — DevOps tutorial

// File: ~/.docker/daemon.json (Mac/Linux) or %USERPROFILE%\.docker\daemon.json (Windows)
// This is the Docker Engine configuration, editable via Docker Desktop GUI or directly.

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "registry-mirrors": [],
  "insecure-registries": []
}

// After editing, click 'Apply & Restart' in Docker Desktop GUI.
// Verify with:
docker info | grep -A5 "Logging Driver"
// Output: Logging Driver: json-file
//         Log: Driver: json-file
//         Log Opt: map[max-file:3 max-size:10m]

Networking — Ports, DNS, and the Localhost Trap

Containers run in their own network namespace. localhost inside a container points to the container, not your host. This confuses everyone.

To access a container from your browser, publish its port: docker run -p 8080:80 nginx. Now http://localhost:8080 reaches the container's port 80.

But here's the trap: on Windows with WSL2, localhost sometimes doesn't work. Use 127.0.0.1 instead. Or use host.docker.internal to reach the host from inside a container.

DNS resolution inside containers uses Docker's embedded DNS server at 127.0.0.11. If you have corporate VPNs or custom DNS, containers may fail to resolve hostnames. Fix: add --dns 8.8.8.8 to your run command, or set dns in docker-compose.

// io.thecodeforge — DevOps tutorial

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

# Test from host
curl http://localhost:8080
# Output: <!DOCTYPE html>... (nginx default page)

# From inside another container, use container name if on same network
docker run --rm alpine ping web
# Output: PING web (172.17.0.2): 56 data bytes
#         64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.123 ms

# To reach host from container (Windows/Mac):
docker run --rm alpine ping host.docker.internal
# Output: PING host.docker.internal (192.168.65.2): 56 data bytes
#         64 bytes from 192.168.65.2: seq=0 ttl=37 time=0.456 ms

# Clean up
docker stop web && docker rm web

Volumes — Persisting Data Without Losing Your Mind

Containers are ephemeral. When you delete a container, its filesystem disappears. That's fine for stateless apps. But databases, caches, and user uploads need to survive.

Volumes are directories on your host that you mount into containers. They persist after container deletion. Use them for anything that must survive.

There are two types: bind mounts (point to a specific host path) and named volumes (managed by Docker). For development, bind mounts let you edit code on your host and see changes in the container. For databases, use named volumes — they're faster and don't depend on host filesystem quirks.

On Windows, bind mounts have a performance penalty because files go through a translation layer. Avoid mounting large directories. Use named volumes for databases.

// io.thecodeforge — DevOps tutorial

# Named volume for Postgres data
docker volume create pgdata
docker run -d --name postgres -v pgdata:/var/lib/postgresql/data -e POSTGRES_PASSWORD=secret postgres:13

# Bind mount for development (Mac/Linux)
docker run -d --name dev -v $(pwd)/src:/app/src node:18 npm run dev

# On Windows PowerShell:
docker run -d --name dev -v ${PWD}/src:/app/src node:18 npm run dev

# Inspect volume location
docker volume inspect pgdata
# Output: [{"Mountpoint": "/var/lib/docker/volumes/pgdata/_data"}]

Troubleshooting — The Three Things That Actually Break

90% of Docker Desktop issues fall into three categories: resource exhaustion, WSL2 corruption, and DNS failures.

Resource exhaustion: containers crash with 'Cannot allocate memory' or 'No space left on device'. Fix: increase memory/disk in settings, run docker system prune -a --volumes, and check log limits.

WSL2 corruption: Docker Desktop won't start, or containers fail with 'The command could not be located because '/usr/bin' is not included in the PATH'. Fix: restart WSL2 with wsl --shutdown, then restart Docker Desktop. If that fails, run wsl --unregister docker-desktop and restart Docker Desktop to recreate the VM.

DNS failures: docker pull hangs with 'Temporary failure in name resolution'. Fix: add "dns": ["8.8.8.8", "1.1.1.1"] to daemon.json. Or restart Docker Desktop after changing VPN.

// io.thecodeforge — DevOps tutorial

# 1. Check resource usage
docker stats --no-stream
# Shows live CPU/Memory per container

# 2. Prune unused data
docker system prune -a --volumes --force

# 3. Restart WSL2 (Windows)
wsl --shutdown
# Then restart Docker Desktop

# 4. Reset Docker Desktop VM (Windows)
wsl --unregister docker-desktop
# Then restart Docker Desktop

# 5. Check Docker daemon logs (Mac)
# Open Console app, search for 'docker'
# Or tail log file:
tail -f ~/Library/Containers/com.docker.docker/Data/log/vm/docker.log

# 6. Check Docker daemon logs (Windows)
# Open Event Viewer -> Windows Logs -> Application
# Filter by source 'Docker'

When Not to Use Docker Desktop

Docker Desktop is for local development. Never use it in production. For production, use Docker Engine on Linux, or a container orchestration platform like Kubernetes or ECS.

Also, if you only need to run a single database locally, consider installing it natively. Docker adds overhead. For a simple Postgres instance, native install is simpler and uses less resources.

If your team is all on Linux, skip Docker Desktop entirely. Install Docker Engine directly. You don't need the VM layer.

And if you're on a resource-constrained machine (8GB RAM or less), Docker Desktop will struggle. Consider using a remote development environment or lightweight alternatives like Podman.