🐳 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 Desktopinstalled (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 compose version

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.

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 3000

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 package*.json ./
RUN npm ci --only=production

COPY src/ ./src/

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

Build and run

docker build -t my-node-app .

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

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: By default, many dev servers bind to--host 0.0.0.0

127.0.0.1

(localhost inside the container). You must bind to0.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

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

docker compose up -d

docker compose logs -f app

docker compose down

docker compose down -v

Part 5: Environment Variables & Secrets #

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

file:

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:

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

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

docker exec -it my-app-container sh

docker run --rm -it node:20-alpine node --version

docker inspect <container_id>

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.

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

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:

Dockerfile basics—FROM

,COPY

,RUN

,CMD

and layer caching - Building & running individual containers withdocker build

/docker run

Docker Compose for multi-service setups (app + database + cache) - Environment variables and keeping secrets out of your images - Dev/prod split using multiple Compose files - Multi-stage builds for lean production images - 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? #

— persisting data beyond the container lifecycleDocker volumes - — custom networking between containersDocker networks - — orchestrating containers at scaleKubernetes - — CI/CD pipelines that build and push images automaticallyGitHub Actions + Docker

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

source & further reading

dev.to — original article Dev Log: 2026-07-07 The Em Dash Isn't the Tell — Your Comment Is Deploying ClearML as a GCP Vertex AI Alternative on Ubuntu