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

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



Tópico: 🐳 How to Run Any Project in Docker: A Complete Guide
Categoria: Tutoriais | Programação & Tecnologia
Idioma Principal: Português (Conteúdo de Tecnologia)

Descrição do Conteúdo / Informações:
-------------------------------------------------------------------------
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:

•
Dockerfile basics — FROM, COPY, RUN, CMD and layer caching

•
Building & running individual containers with docker 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?


•
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.