🐳 How to Run Any Project in Docker: A Complete Guide

From zero to containerized in minutes — no "works on my machine" excuses

---

Why Docker?

You've probably heard it before: "It works on my machine." Docker exists to make that phrase obsolete.

Docker lets you package your application and all its dependencies — runtimes, libraries, config files — into a single, portable unit called a container. That container runs identically on your laptop, your teammate's Windows machine, a CI server, or a cloud VM.

Before we dive in, here's the quick mental model:

• Image → A blueprint (like a class in OOP)
• Container → A running instance of an image (like an object)
• Dockerfile → The recipe for building an image
• Docker Compose → A tool to orchestrate multiple containers together

---

Prerequisites

• Docker Desktop installed (includes Docker Compose)
• Basic terminal familiarity
• A project to containerize (we'll use examples for Node.js, Python, and a generic approach)

Verify your install:

docker --version
# Docker version 26.x.x

docker compose version
# Docker Compose version v2.x.x

---

Part 1: The Anatomy of a Dockerfile

A Dockerfile is a plain text file with instructions Docker reads top-to-bottom to build your image.

# 1. Base image — what you're building ON TOP OF
FROM node:20-alpine

# 2. Set the working directory inside the container
WORKDIR /app

# 3. Copy dependency files first (for layer caching)
COPY package*.json ./

# 4. Install dependencies
RUN npm install

# 5. Copy the rest of your source code
COPY . .

# 6. Expose the port your app listens on
EXPOSE 3000

# 7. The command to run when the container starts
CMD ["node", "server.js"]

Key Instructions Explained

Instruction	Purpose
FROM	Sets the base image. Always the first instruction.
WORKDIR	Sets the working directory for subsequent commands. Created if it doesn't exist.
COPY	Copies files from your host into the image.
RUN	Executes a command during the build phase (installs packages, compiles code).
ENV	Sets environment variables available at runtime.
EXPOSE	Documents which port the app uses (informational; doesn't actually publish).
CMD	The default command when the container starts. Only one per Dockerfile.
ENTRYPOINT	Like CMD, but harder to override — use for "always run this".

Pro tip: Order your Dockerfile from least-to-most frequently changed. Docker caches each layer, so stable layers (like installing dependencies) won't re-run unless they change.

---

Part 2: Dockerizing a Node.js Project

Project structure

my-app/
├── src/
│   └── index.js
├── package.json
├── package-lock.json
└── Dockerfile

Dockerfile

FROM node:20-alpine

WORKDIR /app

# Copy lockfile and package.json first for cache efficiency
COPY package*.json ./
RUN npm ci --only=production

COPY src/ ./src/

EXPOSE 3000
CMD ["node", "src/index.js"]

Build and run

# Build the image and tag it
docker build -t my-node-app .

# Run it, mapping host port 8080 → container port 3000
docker run -p 8080:3000 my-node-app

Visit http://localhost:8080 — your app is running inside Docker.

---

Part 3: Dockerizing a Python Project

FROM python:3.12-slim

WORKDIR /app

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

COPY . .

EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Note the --host 0.0.0.0: By default, many dev servers bind to 127.0.0.1 (localhost inside the container). You must bind to 0.0.0.0 to accept connections from outside the container.

---

Part 4: Docker Compose — Running Multiple Services

Real projects rarely have just one service. You need a database, a cache, maybe a background worker. Docker Compose lets you define and run all of them together.

Example: Node.js app + PostgreSQL + Redis

# docker-compose.yml
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:password@db:5432/mydb
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    volumes:
      - .:/app              # Mount source code for hot reload
      - /app/node_modules   # Prevent host node_modules from overwriting

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 5s
      timeout: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

Run everything with one command

# Start all services in the background
docker compose up -d

# View logs
docker compose logs -f app

# Stop everything
docker compose down

# Stop and remove volumes (wipes database data)
docker compose down -v

---

Part 5: Environment Variables & Secrets

Never hardcode secrets in your Dockerfile or Compose file. Use a .env file:

# .env  (add this to .gitignore!)
POSTGRES_PASSWORD=supersecret
API_KEY=abc123

Docker Compose automatically picks up .env in the same directory:

services:
  app:
    environment:
      - API_KEY=${API_KEY}
  db:
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

For production, use Docker Secrets, Vault, AWS Secrets Manager, or your platform's secret management.

---

Part 6: Development vs Production Configurations

Use multiple Compose files to separate concerns:

my-app/
├── docker-compose.yml          # Base config
├── docker-compose.dev.yml      # Dev overrides (hot reload, debug ports)
└── docker-compose.prod.yml     # Prod overrides (replicas, logging)

docker-compose.dev.yml — adds hot reload:

services:
  app:
    volumes:
      - .:/app
    command: npm run dev
    environment:
      - NODE_ENV=development

docker-compose.prod.yml — tightens things up:

services:
  app:
    restart: always
    environment:
      - NODE_ENV=production
    deploy:
      replicas: 2

Run with merged configs:

# Development
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

---

Part 7: Useful Docker Commands Cheat Sheet

Images

docker images                    # List all local images
docker pull nginx:alpine         # Pull image from Docker Hub
docker rmi my-app                # Remove an image
docker image prune               # Remove unused images

Containers

docker ps                        # List running containers
docker ps -a                     # List all containers (including stopped)
docker stop <container_id>       # Gracefully stop a container
docker rm <container_id>         # Remove a stopped container
docker logs -f <container_id>    # Tail logs from a container
docker exec -it <id> sh          # Open a shell inside a running container

Debugging

# Open an interactive shell in a running container
docker exec -it my-app-container sh

# Run a one-off command
docker run --rm -it node:20-alpine node --version

# Inspect a container's config, network, volumes
docker inspect <container_id>

# Check resource usage
docker stats

---

Part 8: The .dockerignore File

Just like .gitignore, .dockerignore prevents files from being copied into your image. This keeps images small and builds fast.

node_modules
.git
.env
*.log
dist
coverage
.DS_Store
README.md
docker-compose*.yml

Without this, COPY . . would copy your entire node_modules (hundreds of MB) into the image — even though you're running npm install inside it anyway.

---

Part 9: Multi-Stage Builds (Advanced)

Multi-stage builds let you use a heavy build image and copy only the artifacts into a lean production image.

# Stage 1: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build          # Produces /app/dist

# Stage 2: Production
FROM node:20-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY --from=builder /app/dist ./dist   # Only copy built output
EXPOSE 3000
CMD ["node", "dist/server.js"]

The final image contains no TypeScript compiler, test libraries, or source files — just what's needed to run. This can shrink image size from 1GB+ → under 200MB.

---

Common Pitfalls & How to Avoid Them

❌ App can't connect to the database

Inside a Docker network, containers talk to each other by service name, not localhost.

// ❌ Wrong
const db = new Client({ host: 'localhost' })

// ✅ Correct (use the Compose service name)
const db = new Client({ host: 'db' })

❌ Changes not reflected after rebuild

Docker caches layers. Force a full rebuild:

docker compose build --no-cache

❌ Container exits immediately

Check the logs:

docker logs <container_id>

The most common cause: your CMD is wrong, or the process crashes on startup.

❌ Port already in use

Either stop the conflicting service or change the host port mapping:

ports:
  - "3001:3000"   # Map to 3001 on host instead

---

Wrapping Up

Here's what you've learned:

1. Dockerfile basics — FROM, COPY, RUN, CMD and layer caching
2. Building & running individual containers with docker build / docker run
3. Docker Compose for multi-service setups (app + database + cache)
4. Environment variables and keeping secrets out of your images
5. Dev/prod split using multiple Compose files
6. Multi-stage builds for lean production images
7. Debugging techniques when things go sideways

Docker has a learning curve, but once it clicks, you'll never want to go back to "just run it locally". Your entire team gets identical environments, onboarding new developers takes minutes instead of hours, and deployments become deterministic.

---

What's Next?

• Docker volumes — persisting data beyond the container lifecycle
• Docker networks — custom networking between containers
• Kubernetes — orchestrating containers at scale
• GitHub Actions + Docker — CI/CD pipelines that build and push images automatically

---

Found this helpful? Drop a ❤️ and follow for more DevOps and backend content. Got questions? Ask in the comments — I read every one.