Basic Docker Tutorial: Containerize Your App from Scratch

What is Docker?

Docker is an open-source containerization platform that allows developers to package applications along with all their dependencies into lightweight, portable containers. Containers can run on any Docker-supported environment, ensuring that "it works on my machine" means "it works everywhere."

Why Use Docker?

Environment Consistency: Development, testing, and production environments are identical, eliminating the "works on my machine" problem
Lightweight and Fast: Compared to traditional VMs, containers start in seconds and consume fewer resources
Isolation: Each container has its own filesystem, network, and process space
Portability: Build once, run anywhere — Linux, macOS, Windows, and cloud platforms
Easy to Scale: Combine with Docker Compose or Kubernetes to manage multiple services effortlessly

Docker vs Virtual Machines (VMs)

Feature	Docker Container	Virtual Machine
Startup time	Seconds	Minutes
Resource usage	Shares host kernel, very lightweight	Requires full OS, heavy resource usage
Image size	Typically tens to hundreds of MB	Typically several GB
Isolation level	Process-level isolation	Hardware-level isolation
Best for	Microservices, CI/CD, rapid deployment	Full OS requirements or high isolation

Core Concepts

Before getting started with Docker, let's understand a few core concepts:

Image

An image is a read-only template that contains everything needed to run an application: code, runtime, system tools, libraries, and configuration files. Think of an image as a "snapshot" of your application.

Container

A container is a running instance of an image. You can create multiple containers from the same image, and each container is isolated from the others. Containers can be started, stopped, and deleted without affecting the underlying image.

Dockerfile

A Dockerfile is a text file that defines the steps to build an image. It is like a recipe that tells Docker what to do step by step.

Registry

A registry is where images are stored and distributed. The most commonly used is Docker Hub. You can also use GitHub Container Registry or host a private registry.

Volume

A volume is a persistent storage space managed by Docker, used to save data generated by containers. Data in volumes persists even after the container is deleted.

Installing Docker

macOS

Install Docker Desktop using Homebrew:

brew install --cask docker
Loading...

After installation, launch the Docker Desktop application.

Ubuntu / Debian

# Update the package index
sudo apt-get update

# Install required dependencies
sudo apt-get install ca-certificates curl gnupg

# Add Docker's official GPG key
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

# Set up the Docker repository
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

# Install Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
Loading...

Verify Installation

docker --version
docker run hello-world
Loading...

Basic Commands

Image Operations

docker pull <image>            # Pull an image from a registry
docker images                  # List all local images
docker rmi <image>             # Remove an image
docker build -t <name> .       # Build an image from a Dockerfile
docker tag <image> <new-tag>   # Tag an image with a new name
Loading...

Container Operations

docker run <image>             # Create and start a container from an image
docker ps                      # List running containers
docker ps -a                   # List all containers (including stopped)
docker stop <container>        # Stop a container
docker start <container>       # Start a stopped container
docker restart <container>     # Restart a container
docker rm <container>          # Remove a container
docker logs <container>        # View container logs
docker exec -it <container> sh # Enter a running container
Loading...

Common `docker run` Flags

docker run -d <image>                    # Run in detached (background) mode
docker run -p 8080:3000 <image>          # Map host port 8080 to container port 3000
docker run --name my-app <image>         # Name the container
docker run -e NODE_ENV=production <image> # Set environment variable
docker run -v /host/path:/container/path <image>  # Mount a volume
docker run --rm <image>                  # Automatically remove container when stopped
docker run -it <image> sh               # Start in interactive mode with shell
Loading...

System Cleanup

docker system df               # View Docker disk usage
docker system prune            # Clean up unused containers, networks, images
docker system prune -a         # Clean up all unused resources (including images)
docker volume prune            # Clean up unused volumes
Loading...

Writing a Dockerfile

A Dockerfile defines every step of building an image. Here is an example for a Node.js application:

Basic Example

# Use Node.js 20 as the base image
FROM node:20-alpine

# Set the working directory
WORKDIR /app

# Copy package.json and lock file
COPY package.json package-lock.json ./

# Install dependencies
RUN npm ci

# Copy application source code
COPY . .

# Build the application
RUN npm run build

# Expose the port
EXPOSE 3000

# Start the application
CMD ["npm", "start"]
Loading...

Common Instructions

Instruction	Description
`FROM`	Specify the base image
`WORKDIR`	Set the working directory for subsequent instructions
`COPY`	Copy files from the host into the image
`RUN`	Execute a command during the build process
`ENV`	Set environment variables
`EXPOSE`	Declare the port the container will use (for documentation)
`CMD`	Default command to run when the container starts
`ENTRYPOINT`	Entry program when the container starts (harder to override)
`ARG`	Define build-time variables
`VOLUME`	Declare mount points

Multi-stage Build

Multi-stage builds significantly reduce the final image size by separating build tools from the runtime environment:

# === Stage 1: Build ===
FROM node:20-alpine AS builder

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# === Stage 2: Production ===
FROM node:20-alpine AS runner

WORKDIR /app

# Copy only the necessary files
COPY --from=builder /app/package.json ./
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public

ENV NODE_ENV=production
EXPOSE 3000

CMD ["npm", "start"]
Loading...

Benefit: Build-stage tools (dev dependencies, source code) are not included in the final image, significantly reducing its size.

.dockerignore File

Similar to .gitignore, .dockerignore tells Docker which files to exclude during the build:

node_modules
.next
.git
.gitignore
*.md
.env
.env.local
docker-compose.yml

Docker Compose

Docker Compose lets you define and manage multiple container services with a single YAML file. It is ideal for scenarios where multiple services need to run simultaneously (e.g., application + database + reverse proxy).

docker-compose.yml Example

services:
  # Next.js application
  nextjs:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    volumes:
      - ./public:/app/public
    restart: unless-stopped

  # Nginx reverse proxy
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/templates:/etc/nginx/templates
      - ./certbot/conf:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    depends_on:
      - nextjs
    restart: unless-stopped

  # SSL certificate auto-renewal
  certbot:
    image: certbot/certbot
    volumes:
      - ./certbot/conf:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
Loading...

Common Compose Commands

docker compose up                # Start all services (foreground)
docker compose up -d             # Start all services (detached)
docker compose up -d --build     # Rebuild images and start
docker compose down              # Stop and remove all containers
docker compose ps                # View service status
docker compose logs              # View logs for all services
docker compose logs -f <service> # Follow logs for a specific service
docker compose exec <service> sh # Enter a specific service container
docker compose restart <service> # Restart a specific service
docker compose pull              # Pull latest images for all services
Loading...

Common Configuration Options

services:
  app:
    build: .                    # Build from Dockerfile in current directory
    # Or specify detailed build options
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - NODE_ENV=production

    image: my-app:latest        # Use a specific image

    ports:
      - "8080:3000"             # host-port:container-port

    environment:                # Environment variables
      - NODE_ENV=production
      - DB_HOST=database

    env_file:                   # Load env vars from file
      - .env

    volumes:                    # Volume mounts
      - ./data:/app/data        # Bind mount
      - app-data:/app/storage   # Named volume

    depends_on:                 # Service startup order
      - database
      - redis

    restart: unless-stopped     # Restart policy
    # restart: always           # Always restart
    # restart: on-failure       # Restart on failure
    # restart: "no"             # Do not auto-restart

volumes:                        # Define named volumes
  app-data:
Loading...

Networking

Docker containers communicate with each other through networks. Docker Compose automatically creates a default network for all services in the same project.

Basic Network Commands

docker network ls              # List all networks
docker network create <name>   # Create a custom network
docker network inspect <name>  # View network details
docker network rm <name>       # Remove a network
Loading...

Container-to-Container Communication

In Docker Compose, services can communicate with each other directly using service names as hostnames:

services:
  app:
    build: .
    environment:
      - DB_HOST=database    # Use the service name directly

  database:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=secret
Loading...

From the app container, you can connect to the database at database:5432.

Volumes

Containers are "stateless" by default — data is lost when a container is deleted. Use volumes to persist data.

Volume Types

# Named volume (managed by Docker)
docker volume create my-data
docker run -v my-data:/app/data <image>

# Bind mount (maps to a host directory)
docker run -v /host/path:/container/path <image>

# Read-only mount
docker run -v /host/path:/container/path:ro <image>
Loading...

Volume Management Commands

docker volume ls               # List all volumes
docker volume inspect <name>   # View volume details
docker volume rm <name>        # Remove a volume
docker volume prune            # Clean up unused volumes
Loading...

Common Deployment Workflow

Manual Deployment to a VPS

# 1. Verify the build locally
docker compose build

# 2. Push code to the Git remote
git push origin main

# 3. SSH into the server
ssh user@your-server

# 4. Pull the latest code
cd /path/to/project
git pull origin main

# 5. Rebuild and start containers
docker compose up -d --build

# 6. Verify service status
docker compose ps
docker compose logs -f
Loading...

Deploying with Docker Hub

# Local: Build and push the image
docker build -t username/my-app:latest .
docker push username/my-app:latest

# Server: Pull and run
docker pull username/my-app:latest
docker compose up -d
Loading...

Debugging Tips

View Container Status and Logs

docker ps -a                           # View all container statuses
docker logs <container>                # View logs
docker logs -f <container>            # Follow logs in real time
docker logs --tail 100 <container>    # View the last 100 lines of logs
docker inspect <container>            # View full container details
Loading...

Enter a Container for Debugging

docker exec -it <container> sh        # Enter container shell
docker exec -it <container> /bin/bash # Use bash (if available)
Loading...

Common Troubleshooting

Container stops immediately after starting:

# Check the exit status code
docker ps -a
# View logs to find the error
docker logs <container>
Loading...

Port conflict:

# Check which process is using the port
lsof -i :3000
# Or use a different host port
docker run -p 8080:3000 <image>
Loading...

Insufficient disk space:

# Check Docker disk usage
docker system df
# Clean up unused resources
docker system prune -a
Loading...

Best Practices

Use Alpine Images: Choose node:20-alpine over node:20 to reduce image size by hundreds of MB
Use Multi-stage Builds: Separate build and runtime environments to minimize image size
Never Store Secrets in Images: Use environment variables or Docker Secrets to manage passwords and keys
Use .dockerignore: Prevent unnecessary files from being packaged into the image
Pin Image Versions: Use node:20-alpine instead of node:latest to ensure reproducible builds
One Service per Container: Follow the single responsibility principle — run only one main process per container
Leverage Caching: Place infrequently changing steps (like installing dependencies) earlier in the Dockerfile
Set Health Checks: Use the HEALTHCHECK instruction to monitor container health
Use Restart Policies: Set restart: unless-stopped to ensure services recover automatically
Clean Up Regularly: Use docker system prune to remove unused resources and free disk space