How to Set Up Docker for Local Development

Setting up a local development environment often means chasing down dependencies, managing conflicting versions across projects, and dealing with "works on my machine" problems. Docker solves this by packaging your application and its entire runtime environment into containers that run identically everywhere. The setup cost is a few hours of learning Docker fundamentals. The payoff is eliminating environment inconsistencies, simplifying onboarding, and achieving dev-prod parity that actually works.

This guide walks through Docker installation, development workflow configuration, and practical patterns for common tech stacks. You'll learn how to structure Dockerfiles for fast rebuilds, use Docker Compose for multi-service applications, handle file synchronization and hot reloading, and troubleshoot the most common local development issues. The focus is on productive development workflows, not Docker theory.

We'll cover installation, Dockerfile creation, Compose configuration, volume strategies, and debugging—with examples for Node.js, Python, and general web development.

Installing Docker Desktop

Docker Desktop is the standard distribution for Windows and macOS, bundling the Docker Engine, CLI tools, and a GUI for container management. It includes Docker Compose and provides seamless integration with your operating system's file system and networking.

Installation on macOS

Download Docker Desktop from docker.com and install it like any macOS application. Docker Desktop for Mac uses a lightweight VM to run the Docker Engine because Docker requires Linux kernel features. Apple Silicon Macs (M1/M2/M3) run this VM efficiently through Virtualization.framework, providing near-native performance.

After installation, launch Docker Desktop from Applications. The Docker icon appears in your menu bar when the engine is running. Open Terminal and verify installation:

docker --version
docker-compose --version

You should see version numbers for both commands. If not, restart Terminal to pick up PATH changes or restart Docker Desktop.

Installation on Windows

Docker Desktop for Windows requires WSL 2 (Windows Subsystem for Linux) as its backend. Before installing Docker, enable WSL 2:

wsl --install

This installs WSL 2 and a default Linux distribution (usually Ubuntu). Restart your machine when prompted. Then download and install Docker Desktop from docker.com. During installation, ensure "Use WSL 2 instead of Hyper-V" is selected.

Docker Desktop integrates with WSL 2 distributions, letting you run Docker commands from PowerShell, Command Prompt, or inside WSL distributions. For development work, using Docker from within WSL distributions provides better file system performance than accessing Windows paths from containers.

Installation on Linux

Linux users install Docker Engine directly without the Desktop wrapper. The process varies by distribution. For Ubuntu/Debian:

sudo apt-get update
sudo apt-get install 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 docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group to run commands without sudo:

sudo usermod -aG docker $USER
newgrp docker

Verify installation with docker run hello-world. This downloads a test image and runs a container that prints a confirmation message.

Understanding Docker Development Workflow

A typical Docker development workflow involves creating a Dockerfile that defines your application's environment, building that Dockerfile into an image, and running containers from that image. For local development, you mount your source code into the container as a volume so changes you make in your editor immediately appear inside the container without rebuilding.

The Dockerfile specifies the base image (operating system and runtime), installs dependencies, copies application code, and defines how to run the application. During development, you optimize Dockerfiles for fast rebuilds by leveraging layer caching—Docker caches each instruction's result and reuses it if the instruction hasn't changed.

Basic Dockerfile Structure

Here's a development Dockerfile for a Node.js application:

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 3000

CMD ["npm", "run", "dev"]

This Dockerfile uses the official Node.js 18 Alpine image (a lightweight Linux distribution). The WORKDIR instruction sets the working directory inside the container. Copying package*.json before copying the rest of the code is a layer caching optimization—dependencies only reinstall when package files change, not when you modify application code.

The EXPOSE instruction documents which port the application uses (it doesn't actually publish the port—that happens when you run the container). The CMD instruction specifies the default command to run when the container starts.

Python Development Dockerfile

For Python applications, the pattern is similar:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

The --no-cache-dir flag tells pip not to store downloaded packages, reducing image size. Binding to 0.0.0.0 instead of localhost is crucial—containers need to listen on all interfaces for the host to connect.

Using Docker Compose for Multi-Service Development

Most applications depend on services like databases, caches, or message queues. Docker Compose orchestrates multiple containers, defining them in a docker-compose.yml file. This eliminates manual container management and ensures consistent startup of all dependencies.

A compose file for a web application with a database looks like this:

version: '3.8'

services:
  web:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      DATABASE_URL: postgres://postgres:password@db:5432/myapp
      NODE_ENV: development
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres_data:

The web service builds from the Dockerfile in the current directory (build: .). It mounts the current directory to /app inside the container so code changes appear immediately. The /app/node_modules volume prevents the host's node_modules (if any) from overriding the container's dependencies.

The db service uses the official PostgreSQL image. The named volume postgres_data persists database data across container restarts. The depends_on directive ensures the database starts before the web service, though it doesn't wait for PostgreSQL to be ready—it only controls startup order.

Starting Your Development Environment

With this compose file in place, start everything with:

docker-compose up

Docker Compose builds images (if needed), creates networks, and starts containers. Logs from all services appear in your terminal, color-coded by service. Run in detached mode to free your terminal:

docker-compose up -d

View logs with docker-compose logs -f or for a specific service: docker-compose logs -f web. Stop everything with docker-compose down. Add -v to also remove volumes (deletes database data):

docker-compose down -v

Volume Strategies for Hot Reloading

Mounting your source code as a volume enables hot reloading—your application inside the container detects file changes and reloads automatically, just like local development without Docker. The volumes section in your compose file controls this:

volumes:
  - .:/app
  - /app/node_modules

The first line (.:/app) mounts the current directory on your host to /app in the container. The second line (/app/node_modules) creates an anonymous volume that overrides the host's node_modules directory. This is necessary because node_modules installed in the container (potentially for a different OS or architecture) shouldn't be overridden by host files.

Handling File Permissions on Linux

On Linux, files created by containers are owned by root unless you specify otherwise. This causes permission issues when editing files. The solution is running the container process as your user ID:

services:
  web:
    build: .
    user: "${UID}:${GID}"
    volumes:
      - .:/app

Set UID and GID in a .env file in the same directory as your compose file:

UID=1000
GID=1000

Find your UID and GID with id command. This ensures files created inside the container have the same ownership as your user.

Volume Performance on macOS and Windows

File system performance can be problematic on macOS and Windows because Docker Desktop uses a VM with shared folders. Applications with many small file operations (like Node.js with node_modules) may run slower than natively. Several mitigation strategies exist:

For macOS, use delegated volume mounts:

volumes:
  - .:/app:delegated
  - /app/node_modules

The :delegated flag tells Docker that the container's view of the volume can be temporarily inconsistent with the host, improving performance by batching file system operations.

For Windows, keep your code in the WSL file system and develop from inside WSL. File operations on WSL paths are significantly faster than mounting Windows paths into containers.

Alternatively, use named volumes for dependency directories to avoid mounting them from the host:

volumes:
  - .:/app:delegated
  - node_modules_cache:/app/node_modules

volumes:
  node_modules_cache:

This keeps node_modules entirely inside Docker volumes, avoiding host file system overhead for those files.

Development-Specific Docker Patterns

Using Multi-Stage Builds for Development and Production

Multi-stage Dockerfiles let you define different build targets for development and production. A development stage includes debugging tools and hot reloading, while a production stage optimizes for size and security:

FROM node:18-alpine AS development

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 3000
CMD ["npm", "run", "dev"]

FROM node:18-alpine AS production

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 3000
CMD ["node", "server.js"]

Build the development stage by default or specify the target explicitly:

docker build --target development -t myapp:dev .

In your compose file, specify the target stage:

services:
  web:
    build:
      context: .
      target: development

Environment Variables and Secrets

Development environments need different configuration than production. Docker Compose supports environment variables through multiple methods. The simplest is a .env file:

DATABASE_URL=postgres://postgres:password@db:5432/myapp
API_KEY=dev_key_12345
NODE_ENV=development

Reference these in your compose file:

services:
  web:
    build: .
    environment:
      - DATABASE_URL
      - API_KEY
      - NODE_ENV

Or load the entire .env file:

services:
  web:
    build: .
    env_file:
      - .env

For secrets that shouldn't be in version control, add .env to .gitignore and provide a .env.example file with placeholder values that team members copy and customize.

Database Development Patterns

Running databases in Docker for local development is standard practice. The pattern is straightforward—use official images, persist data with volumes, and expose ports for direct access when needed.

PostgreSQL Development Setup

services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp_dev
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql
    ports:
      - "5432:5432"

volumes:
  postgres_data:

The volume mount to /docker-entrypoint-initdb.d/ automatically runs initialization scripts when the database is first created. This is useful for creating schemas, loading seed data, or setting up extensions.

Exposing port 5432 to the host lets you connect with database tools like pgAdmin, Postico, or psql directly from your machine. Your application connects using the service name as hostname: postgres://postgres:password@db:5432/myapp_dev.

MySQL Development Setup

services:
  db:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: myapp_dev
      MYSQL_USER: appuser
      MYSQL_PASSWORD: password
    volumes:
      - mysql_data:/var/lib/mysql
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql
    ports:
      - "3306:3306"
    command: --default-authentication-plugin=mysql_native_password

volumes:
  mysql_data:

The command override sets MySQL to use native password authentication, which is more compatible with older client libraries. MySQL images also support initialization scripts in /docker-entrypoint-initdb.d/.

Redis and Other Services

Adding Redis for caching or session storage:

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  redis_data:

Redis persists data to /data inside the container, which the volume preserves. For development, persistence isn't always necessary—you might remove the volume to start fresh on each restart.

Running Commands Inside Containers

During development, you often need to run one-off commands—database migrations, dependency updates, or interactive shells. Docker Compose makes this straightforward:

docker-compose exec web npm install new-package
docker-compose exec web npm run migrate
docker-compose exec db psql -U postgres myapp_dev

The exec command runs a command in an already-running container. To run a command in a new container instance:

docker-compose run --rm web npm run migrate

The --rm flag removes the container after the command completes, preventing container clutter.

Opening Interactive Shells

For debugging or exploration, open a shell inside a container:

docker-compose exec web sh

Alpine-based images use sh instead of bash. Debian-based images support bash:

docker-compose exec web bash

Inside the shell, you have access to your application code, installed dependencies, and the container's file system. This is useful for diagnosing issues, inspecting logs, or manually testing components.

Debugging Applications Running in Docker

Debugging containerized applications works differently than debugging local processes. You need to expose debugger ports and configure your IDE to connect to the container.

Node.js Debugging

To debug a Node.js application, run it with the inspect flag and expose the debug port:

services:
  web:
    build: .
    command: node --inspect=0.0.0.0:9229 server.js
    ports:
      - "3000:3000"
      - "9229:9229"
    volumes:
      - .:/app
      - /app/node_modules

Configure VS Code to attach to this debugger by adding to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Docker: Attach to Node",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "address": "localhost",
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/app",
      "protocol": "inspector"
    }
  ]
}

Start your containers, then use VS Code's debugger to attach. Set breakpoints, and they'll work just like local debugging.

Python Debugging with pdb

For Python applications, using pdb requires running the container in interactive mode with stdin attached:

docker-compose run --rm --service-ports web python -m pdb manage.py runserver 0.0.0.0:8000

The --service-ports flag ensures port mappings from the compose file are used. For remote debugging with VS Code or PyCharm, use debugpy:

services:
  web:
    build: .
    command: python -m debugpy --listen 0.0.0.0:5678 manage.py runserver 0.0.0.0:8000
    ports:
      - "8000:8000"
      - "5678:5678"

Install debugpy in your container and configure your IDE to connect to port 5678.

Optimizing Docker Build Speed

Slow builds kill development productivity. Docker's layer caching is key to fast rebuilds—structure Dockerfiles to maximize cache hits.

Layer Caching Best Practices

Copy dependency manifests before application code so dependency installation layers cache independently:

COPY package*.json ./
RUN npm install

COPY . .

If you copy everything first, changing any source file invalidates the npm install cache. With separate copy steps, only changes to package files trigger dependency reinstallation.

Use .dockerignore to exclude files that change frequently but don't affect the build:

node_modules
.git
.env
*.log
.DS_Store
README.md

This reduces the build context size and prevents unnecessary cache invalidation from irrelevant file changes.

BuildKit for Faster Builds

Enable Docker BuildKit for improved caching, parallel build stages, and better performance:

export DOCKER_BUILDKIT=1
docker build .

Make this permanent by adding to your shell configuration (~/.bashrc or ~/.zshrc):

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

BuildKit also supports cache mounts that persist between builds:

RUN --mount=type=cache,target=/root/.npm \
    npm install

This caches npm's download directory across builds, avoiding re-downloading packages.

Common Local Development Issues and Solutions

Port Already in Use

Error: Bind for 0.0.0.0:3000 failed: port is already allocated. This means another process is using the port. Find and stop it:

lsof -i :3000
kill -9 

Or change the port mapping in your compose file:

ports:
  - "3001:3000"

This maps host port 3001 to container port 3000, avoiding the conflict.

Changes Not Appearing in Container

If code changes don't trigger hot reloading, verify volume mounts are correct. Check with:

docker-compose exec web ls -la /app

Your source files should appear. If not, the volume mount is misconfigured. Ensure the path in volumes section matches your project structure.

On Windows with WSL2, ensure your code is in the WSL file system (/home/user/project) not Windows paths (/mnt/c/Users/...).

Permission Denied Errors

On Linux, permission errors occur when container processes create files owned by root. Set the container user to match your UID:

user: "${UID}:${GID}"

And define these in a .env file. Alternatively, fix permissions after the fact:

sudo chown -R $USER:$USER .

Container Exits Immediately

If a container starts and immediately exits, check logs:

docker-compose logs web

Common causes include syntax errors in your application, missing environment variables, or incorrect command definitions. The logs usually reveal the issue.

Database Connection Refused

If your application can't connect to the database, verify the database service is running:

docker-compose ps

Check that your connection string uses the service name as hostname (db, not localhost). Services communicate through Docker's internal network using service names.

If the database is starting but not ready when your application connects, add a wait script or use a tool like wait-for-it:

services:
  web:
    build: .
    depends_on:
      - db
    command: sh -c "wait-for-it db:5432 -- npm run dev"

Integration with IDEs and Tools

VS Code Docker Extension

The official Docker extension for VS Code provides container management, log viewing, and file system browsing from the IDE. Install it from the Extensions marketplace (search "Docker"). It adds a Docker icon to the sidebar where you can view running containers, images, networks, and volumes.

You can right-click containers to view logs, open shells, or stop/restart them without touching the command line. The extension also provides IntelliSense for Dockerfiles and docker-compose.yml files.

Remote Development in Containers

VS Code's Remote-Containers extension (now called Dev Containers) lets you develop inside a container with full IDE features. Create a .devcontainer/devcontainer.json file:

{
  "name": "My App",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "web",
  "workspaceFolder": "/app",
  "extensions": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode"
  ]
}

Open the command palette (Cmd+Shift+P) and run "Remote-Containers: Reopen in Container". VS Code restarts with the editor running inside your container. Extensions, terminal, and debugging all work inside the container environment. This eliminates host/container environment differences entirely.

JetBrains IDEs

WebStorm, PyCharm, and other JetBrains IDEs support Docker interpreters and run configurations. Configure the Node.js or Python interpreter to use the Docker container. The IDE handles running code, tests, and debugging inside the container while you edit code normally.

Configure this in Settings → Languages & Frameworks → Node.js (or Python) → Add Remote Interpreter → Docker Compose, then select your service. The IDE automatically maps paths and handles port forwarding.

Docker Compose Override for Local Customization

Team members often need different local configurations—different port mappings, extra services, or environment-specific settings. Docker Compose supports override files for this. Create docker-compose.override.yml (automatically loaded when it exists):

version: '3.8'

services:
  web:
    ports:
      - "3001:3000"
    environment:
      DEBUG: "true"

This file merges with docker-compose.yml, overriding or adding to the base configuration. Add docker-compose.override.yml to .gitignore so it stays local. Provide a docker-compose.override.yml.example with common overrides as a starting point.

Production-Like Local Testing

Sometimes you need to test production builds locally. Create a separate compose file for this:

version: '3.8'

services:
  web:
    build:
      context: .
      target: production
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://postgres:password@db:5432/myapp
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Run this with:

docker-compose -f docker-compose.prod.yml up

This builds and runs the production target from your multi-stage Dockerfile, letting you verify production behavior before deploying.

Cleaning Up Docker Resources

Docker accumulates images, containers, volumes, and networks over time. Periodic cleanup prevents disk space issues:

docker system prune

This removes stopped containers, unused networks, and dangling images (untagged images from intermediate build steps). Add -a to also remove unused images:

docker system prune -a

Remove unused volumes separately (this deletes data):

docker volume prune

For more aggressive cleanup, remove everything not currently in use:

docker system prune -a --volumes

Frequently Asked Questions

Do I need to rebuild my Docker image after every code change?

No, and you shouldn't during development. Mount your source code as a volume so changes appear inside the container immediately without rebuilding. Rebuilding is only necessary when you change dependencies (package.json, requirements.txt) or Dockerfile instructions. Hot reloading frameworks like nodemon or Django's runserver detect file changes through the volume mount and reload automatically.

Why is my Docker build using an old version of my code?

Docker's layer caching might be serving stale layers. Force a fresh build with docker-compose build --no-cache. This rebuilds all layers from scratch, ignoring the cache. For faster rebuilds while still invalidating cache, update a dependency or add a meaningless instruction like ENV CACHE_BUST=1 and increment it to force cache invalidation from that point forward.

How do I use different environment variables for different team members?

Use .env files that are git-ignored and provide a .env.example template. Each developer copies .env.example to .env and customizes it. Docker Compose automatically loads .env if it exists. Alternatively, use docker-compose.override.yml (also git-ignored) for developer-specific configuration overrides.

Can I run multiple projects with Docker Compose simultaneously?

Yes, but they must use different port mappings or project names. Docker Compose uses the directory name as the project name by default, which namespaces containers, networks, and volumes. If two projects have services listening on port 3000, map them to different host ports: 3000:3000 for one project and 3001:3000 for another. Or use the -p flag to override project names: docker-compose -p project1 up.

Why is file watching not working with my hot reload setup?

Some file watching systems struggle with Docker volumes, especially on macOS and Windows. For Node.js, use polling mode in nodemon by setting --legacy-watch. For webpack, enable polling: watchOptions: { poll: 1000 }. Polling is less efficient but more reliable with Docker volumes. On macOS, ensure you're using the latest Docker Desktop version, as file system performance and event propagation have improved significantly in recent releases.

Should I commit docker-compose.yml to git?

Yes, docker-compose.yml is part of your project's infrastructure definition and should be versioned. It ensures all team members and CI systems use the same development environment. Commit Dockerfile and docker-compose.yml but not .env or docker-compose.override.yml, which contain local-specific or sensitive configuration.

How do I share a database dump with my team using Docker?

Place SQL dump files in a directory and mount it to the database container's initialization directory. For PostgreSQL: ./db/init.sql:/docker-entrypoint-initdb.d/init.sql. The container runs these scripts on first startup. Commit the dump files to git, and new team members get the database seeded automatically. For large dumps, store them externally and document the download/import process in your README.

Can I use Docker for frontend development with tools like Create React App?

Yes, though some developers find it adds unnecessary complexity for frontend-only projects. Create React App's development server works in Docker with volume mounts, but you need to expose environment variables and potentially use polling for hot module replacement. The docker-compose.yml would mount your source code and forward port 3000. Whether this adds value depends on whether you need consistency across team environments or just want to use local Node.js installations.

What's the difference between CMD and ENTRYPOINT in a Dockerfile?

CMD defines the default command to run when the container starts, and it's easily overridden: docker run myimage npm test replaces the CMD. ENTRYPOINT defines a command that always runs, with arguments appended: if ENTRYPOINT ["npm"], then docker run myimage test runs npm test. For development Dockerfiles, CMD is usually sufficient because you override commands frequently with docker-compose or docker run arguments.

How do I update to the latest version of an official Docker image?

Pull the latest tag explicitly: docker pull postgres:latest. Using :latest in your compose file (or omitting the tag, which defaults to latest) doesn't automatically pull updates—Docker uses the cached image. For reproducibility, pin specific versions in production (postgres:15.2) and use :latest or version ranges only in development where you want automatic updates.

Conclusion

Docker transforms local development by eliminating environment inconsistencies, simplifying dependency management, and ensuring dev-prod parity. The initial setup investment—learning Dockerfile and Docker Compose syntax, configuring volume mounts, and adapting workflows—pays off through faster onboarding, fewer environment issues, and portable development environments.

Start with a simple Dockerfile and compose configuration for your primary application and database. Add volumes for hot reloading, expose necessary ports, and verify that code changes appear without rebuilding. Gradually refine the setup based on actual development friction—add debugging support when you need it, optimize build speed when it becomes a bottleneck, integrate with your IDE when command-line workflows feel cumbersome.

The goal is development velocity, not Docker mastery. Use Docker to remove obstacles to productivity, not to create new ones. A well-configured Docker development environment should be mostly invisible—just like a good development setup without Docker.