Beginner

# Pull and run hello-world image
docker run hello-world
# => Unable to find image 'hello-world:latest' locally
# => latest: Pulling from library/hello-world
# => Status: Downloaded newer image for hello-world:latest
# => Output: Hello from Docker!
# => Output: This message shows that your installation appears to be working correctly.

# List all containers (including stopped)
docker ps -a
# => CONTAINER ID   IMAGE         COMMAND    CREATED        STATUS                    PORTS     NAMES
# => abc123def456   hello-world   "/hello"   5 seconds ago  Exited (0) 4 seconds ago            quirky_name

# Run Ubuntu container with interactive shell
docker run -it ubuntu:22.04 bash
# => Unable to find image 'ubuntu:22.04' locally
# => Status: Downloaded newer image for ubuntu:22.04
# => Prompt changes to: root@container_id:/#

# Inside container: Check OS version
cat /etc/os-release
# => Output: Ubuntu 22.04.3 LTS

# Inside container: List files
ls /
# => Output: bin boot dev etc home lib media mnt opt proc root run sbin srv sys tmp usr var

# Exit container (stops it)
exit
# => Returns to host shell
# => Container stops when interactive shell exits

# File: Dockerfile

# Base image with Node.js runtime
FROM node:18-alpine
# => Pulls official Node.js 18 image based on Alpine Linux (~40MB)
# => Alpine provides minimal footprint for production containers

# Set working directory
WORKDIR /app
# => Creates /app directory if it doesn't exist
# => All subsequent commands run in /app

# Copy application file
COPY server.js .
# => Copies server.js from build context to /app/
# => Creates a layer with the file

# Expose port (documentation only)
EXPOSE 3000
# => Documents that container listens on port 3000
# => Does NOT actually publish the port (need -p flag)

# Default command
CMD ["node", "server.js"]
# => Command executed when container starts
# => Can be overridden with docker run arguments

// File: server.js
const http = require("http");

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("Hello from Docker!\n");
});

server.listen(3000, () => {
  console.log("Server running on port 3000");
});

# Build image
docker build -t my-node-app .
# => Sends build context to Docker daemon
# => Step 1/4: FROM node:18-alpine (base layer)
# => Step 2/4: WORKDIR /app (filesystem layer)
# => Step 3/4: COPY server.js . (application layer)
# => Step 4/4: CMD ["node", "server.js"] (metadata only)
# => Successfully tagged my-node-app:latest

# Run container with port mapping
docker run -p 3000:3000 my-node-app
# => Output: Server running on port 3000
# => Maps host port 3000 to container port 3000

# Test from host (in another terminal)
curl http://localhost:3000
# => Output: Hello from Docker!

# File: Dockerfile

FROM node:18-alpine
# => Base image with Node.js runtime

WORKDIR /app
# => Working directory for all subsequent commands

# Copy package files first (separate layer for caching)
COPY package*.json ./
# => Copies package.json and package-lock.json to /app/
# => This layer is cached unless package files change

# Install dependencies
RUN npm ci --only=production
# => npm ci installs exact versions from package-lock.json
# => --only=production skips devDependencies
# => Creates layer with node_modules/ (can be large)

# Copy source code (changes frequently)
COPY . .
# => Copies all remaining files to /app/
# => Separate layer allows rebuilding without reinstalling dependencies

EXPOSE 8080
# => Documents container port

CMD ["node", "app.js"]
# => Starts application

// File: package.json
{
  "name": "docker-app",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0"
  }
}

// File: app.js
const express = require("express");
const app = express();

app.get("/", (req, res) => {
  res.send("Express app running in Docker!");
});

app.listen(8080, () => {
  console.log("App listening on port 8080");
});

# First build (installs dependencies)
docker build -t my-express-app .
# => [1/5] FROM node:18-alpine
# => [2/5] WORKDIR /app
# => [3/5] COPY package*.json ./
# => [4/5] RUN npm ci --only=production (takes ~30 seconds)
# => [5/5] COPY . .
# => Build time: ~35 seconds

# Modify app.js and rebuild
echo "// Updated" >> app.js
docker build -t my-express-app .
# => [1/5] FROM node:18-alpine (cached)
# => [2/5] WORKDIR /app (cached)
# => [3/5] COPY package*.json ./ (cached)
# => [4/5] RUN npm ci --only=production (cached - package files unchanged!)
# => [5/5] COPY . . (rebuilds - source changed)
# => Build time: ~2 seconds (dependency layer cached!)

# File: Dockerfile

FROM node:18-alpine
# => Base image

# Define build argument with default value
ARG NODE_ENV=production
# => Declares NODE_ENV variable available during build
# => Default value is "production" if not overridden

# Use build argument during build
RUN echo "Building for environment: $NODE_ENV"
# => Accesses ARG value during image build
# => Output shows during docker build execution

WORKDIR /app
COPY package*.json ./

# Conditional dependency installation based on build arg
RUN if [ "$NODE_ENV" = "development" ]; then \
      npm ci; \
    else \
      npm ci --only=production; \
    fi
# => Installs all dependencies for development
# => Skips devDependencies for production
# => Bash conditional statement inside RUN

COPY . .

# Convert ARG to ENV for runtime access
ENV NODE_ENV=$NODE_ENV
# => Makes NODE_ENV available at runtime
# => ARG alone would not be available when container runs

EXPOSE 8080
CMD ["node", "app.js"]

# Build with default ARG value (production)
docker build -t my-app:prod .
# => Uses ARG NODE_ENV=production (default)
# => Output: Building for environment: production
# => Installs only production dependencies

# Build with custom ARG value (development)
docker build --build-arg NODE_ENV=development -t my-app:dev .
# => Overrides NODE_ENV to "development"
# => Output: Building for environment: development
# => Installs all dependencies including devDependencies

# Inspect environment variables in running container
docker run --rm my-app:prod printenv NODE_ENV
# => Output: production (ENV persists at runtime)

# File: Dockerfile

FROM node:18-alpine
# => Base image

WORKDIR /app

# Set environment variables (persist at runtime)
ENV NODE_ENV=production
# => Sets NODE_ENV for all RUN, CMD, and ENTRYPOINT instructions
# => Available in running container

ENV PORT=3000
# => Application port configuration

ENV LOG_LEVEL=info
# => Application logging configuration

COPY package*.json ./
RUN npm ci --only=production
# => npm respects NODE_ENV variable during installation

COPY . .

EXPOSE $PORT
# => Uses PORT variable value (expands to 3000)

CMD ["node", "server.js"]
# => Application reads ENV variables at runtime

// File: server.js
const http = require("http");

// Read environment variables
const port = process.env.PORT || 3000; // => 3000 from ENV PORT
const nodeEnv = process.env.NODE_ENV || "dev"; // => "production" from ENV NODE_ENV
const logLevel = process.env.LOG_LEVEL || "debug"; // => "info" from ENV LOG_LEVEL

console.log(`Environment: ${nodeEnv}`); // => Output: Environment: production
console.log(`Log Level: ${logLevel}`); // => Output: Log Level: info

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(
    JSON.stringify({
      env: nodeEnv,
      port: port,
      logLevel: logLevel,
    }),
  );
});

server.listen(port, () => {
  console.log(`Server on port ${port}`); // => Output: Server on port 3000
});

# Run with default ENV values
docker run -p 3000:3000 --name app1 my-app
# => Output: Environment: production
# => Output: Log Level: info
# => Output: Server on port 3000

# Override ENV at runtime with -e flag
docker run -p 3001:3001 -e PORT=3001 -e LOG_LEVEL=debug --name app2 my-app
# => Overrides PORT and LOG_LEVEL
# => Output: Environment: production (not overridden)
# => Output: Log Level: debug (overridden)
# => Output: Server on port 3001 (overridden)

# Check environment variables in running container
docker exec app1 printenv
# => Output includes: NODE_ENV=production, PORT=3000, LOG_LEVEL=info

# File: Dockerfile

FROM python:3.11-slim
# => Base image with Python runtime

# Add metadata labels
LABEL maintainer="devops@example.com"
# => Contact information for image maintainer

LABEL version="1.0.0"
# => Semantic version of this image

LABEL description="Python web application with Flask"
# => Human-readable description

LABEL org.opencontainers.image.source="https://github.com/example/repo"
# => Source repository URL (OCI standard)

LABEL org.opencontainers.image.licenses="MIT"
# => License information (OCI standard)

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# => --no-cache-dir reduces image size

COPY app.py .

EXPOSE 5000
CMD ["python", "app.py"]

# File: app.py
from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return 'Flask app in Docker!'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

# File: requirements.txt
Flask==2.3.0

# Build image with labels
docker build -t my-flask-app:1.0.0 .
# => Successfully tagged my-flask-app:1.0.0

# Inspect image labels
docker inspect my-flask-app:1.0.0 --format='{{json .Config.Labels}}' | jq
# => Output (formatted JSON):
# => {
# =>   "maintainer": "devops@example.com",
# =>   "version": "1.0.0",
# =>   "description": "Python web application with Flask",
# =>   "org.opencontainers.image.source": "https://github.com/example/repo",
# =>   "org.opencontainers.image.licenses": "MIT"
# => }

# Filter images by label
docker images --filter "label=version=1.0.0"
# => Shows only images with version=1.0.0 label

# Use labels in container orchestration
docker run -d \
  --label environment=production \
  --label team=backend \
  -p 5000:5000 \
  my-flask-app:1.0.0
# => Adds runtime labels to container (separate from image labels)

# List all images
docker images
# => REPOSITORY       TAG       IMAGE ID       CREATED         SIZE
# => my-flask-app     1.0.0     abc123def456   2 minutes ago   145MB
# => node             18-alpine 789ghi012jkl   2 weeks ago     119MB
# => python           3.11-slim 345mno678pqr   1 month ago     126MB

# List images with digests (immutable identifier)
docker images --digests
# => Shows SHA256 digest after tag column
# => Digest uniquely identifies image content

# Filter images by name
docker images my-flask-app
# => Shows only my-flask-app images

# Filter dangling images (untagged intermediate layers)
docker images --filter "dangling=true"
# => Lists images not referenced by any tag
# => Often left over from rebuilds

# Show image history (layer details)
docker history my-flask-app:1.0.0
# => IMAGE          CREATED        CREATED BY                                      SIZE
# => abc123def456   5 minutes ago  CMD ["python" "app.py"]                         0B
# => <missing>      5 minutes ago  EXPOSE 5000                                     0B
# => <missing>      5 minutes ago  COPY app.py . # buildkit                        1.2kB
# => <missing>      5 minutes ago  RUN pip install --no-cache-dir -r requirements  15MB
# => Shows each layer with size and command

# Tag image with additional name
docker tag my-flask-app:1.0.0 my-flask-app:latest
# => Creates new tag pointing to same image
# => No disk space used (same image ID)

# Remove specific image tag
docker rmi my-flask-app:1.0.0
# => Untagged: my-flask-app:1.0.0
# => Image still exists as my-flask-app:latest

# Remove image and all tags
docker rmi $(docker images my-flask-app -q)
# => Removes all tags for my-flask-app
# => -q returns only image IDs

# Prune dangling images (cleanup)
docker image prune
# => Removes all dangling images
# => Frees disk space

# Prune all unused images
docker image prune -a
# => Removes all images not used by containers
# => Use with caution - removes ALL unused images

# Create container without starting it
docker create --name my-nginx -p 8080:80 nginx:alpine
# => Creates container in "Created" state
# => Container ID: def456ghi789
# => Port mapping configured but not active yet

# List all containers (including created/stopped)
docker ps -a
# => CONTAINER ID   IMAGE         STATUS    PORTS                  NAMES
# => def456ghi789   nginx:alpine  Created   0.0.0.0:8080->80/tcp   my-nginx

# Start created container
docker start my-nginx
# => Transitions container to "Running" state
# => Port 8080 now accessible

# Check running containers only
docker ps
# => CONTAINER ID   IMAGE         STATUS        PORTS                  NAMES
# => def456ghi789   nginx:alpine  Up 5 seconds  0.0.0.0:8080->80/tcp   my-nginx

# Pause running container (freezes all processes)
docker pause my-nginx
# => Container state: Paused
# => Processes suspended but container still exists
# => Port still mapped but requests hang

# Unpause container
docker unpause my-nginx
# => Resumes all processes
# => Container returns to Running state

# Stop container gracefully (SIGTERM, then SIGKILL after 10s)
docker stop my-nginx
# => Sends SIGTERM to main process
# => Waits up to 10 seconds for graceful shutdown
# => Sends SIGKILL if still running after timeout
# => Container state: Exited

# Restart stopped container
docker restart my-nginx
# => Equivalent to docker stop + docker start
# => Container returns to Running state

# Stop container with custom timeout
docker stop -t 30 my-nginx
# => Waits 30 seconds before SIGKILL (instead of default 10)

# Kill container immediately (SIGKILL, no graceful shutdown)
docker kill my-nginx
# => Sends SIGKILL immediately
# => Use when container doesn't respond to stop

# Remove stopped container
docker rm my-nginx
# => Deletes container completely
# => Cannot be started again

# Remove running container (force)
docker rm -f my-nginx
# => Stops (SIGKILL) and removes in one command
# => Use with caution - no graceful shutdown

# Run container that generates logs
docker run -d --name web-app -p 8080:80 nginx:alpine
# => Container ID: abc123def456
# => Runs in background (-d detached mode)

# View logs (stdout and stderr)
docker logs web-app
# => /docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
# => /docker-entrypoint.sh: Configuration complete; ready for start up
# => Shows all logs since container start

# Follow logs in real-time (like tail -f)
docker logs -f web-app
# => Streams new log lines as they appear
# => Press Ctrl+C to stop following

# Show timestamps with logs
docker logs -t web-app
# => 2025-12-29T10:30:15.123456789Z /docker-entrypoint.sh: Launching...
# => 2025-12-29T10:30:15.234567890Z Configuration complete
# => Each line prefixed with RFC3339 timestamp

# Show only last N lines
docker logs --tail 20 web-app
# => Shows last 20 log lines
# => Useful for large log volumes

# Show logs since specific time
docker logs --since 10m web-app
# => Shows logs from last 10 minutes
# => Accepts format: 10s, 5m, 2h, 2023-12-29T10:00:00

# Inspect container details (JSON output)
docker inspect web-app
# => Returns JSON with full container configuration
# => Includes: networking, volumes, environment, state, etc.

# Extract specific information with format
docker inspect --format='{{.State.Status}}' web-app
# => Output: running

docker inspect --format='{{.NetworkSettings.IPAddress}}' web-app
# => Output: 172.17.0.2 (container IP on bridge network)

docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web-app
# => Output: 172.17.0.2
# => More reliable for multiple networks

docker inspect --format='{{json .Config.Env}}' web-app | jq
# => Shows environment variables as formatted JSON

# View container stats (CPU, memory, network, I/O)
docker stats web-app
# => CONTAINER ID   NAME      CPU %   MEM USAGE / LIMIT   MEM %   NET I/O       BLOCK I/O
# => abc123def456   web-app   0.01%   5.5MiB / 7.77GiB    0.07%   1.2kB / 0B    0B / 0B
# => Updates every second (live monitoring)

# View stats once (no streaming)
docker stats --no-stream web-app
# => Shows current stats snapshot
# => Exits immediately

# Start a web container
docker run -d --name web-server -p 8080:80 nginx:alpine
# => Container running in background

# Execute single command in container
docker exec web-server ls -la /usr/share/nginx/html
# => total 8
# => drwxr-xr-x 2 root root 4096 Dec 29 10:00 .
# => drwxr-xr-x 3 root root 4096 Dec 29 10:00 ..
# => -rw-r--r-- 1 root root  615 Nov 10 12:00 index.html
# => Lists files in nginx web root

# Execute command with output redirection
docker exec web-server sh -c 'echo "Hello Docker" > /tmp/greeting.txt'
# => Creates file inside container
# => Returns no output (stdout redirected to file)

docker exec web-server cat /tmp/greeting.txt
# => Output: Hello Docker

# Start interactive shell in running container
docker exec -it web-server sh
# => Opens interactive shell inside container
# => Prompt changes to: / #

# Inside container: Install debugging tools
apk add curl
# => Installs curl inside container
# => Changes persist only while container runs

curl http://localhost
# => Tests nginx from inside container
# => Output: <!DOCTYPE html>...

exit
# => Returns to host shell
# => Container keeps running (exec doesn't affect main process)

# Execute command as specific user
docker exec -u nginx web-server whoami
# => Output: nginx
# => Runs command as nginx user instead of root

# Execute command with environment variables
docker exec -e DEBUG=true web-server sh -c 'echo $DEBUG'
# => Output: true
# => Temporary environment variable for this exec only

# Execute command in specific working directory
docker exec -w /etc/nginx web-server pwd
# => Output: /etc/nginx
# => Sets working directory for command

# Run background process inside container
docker exec -d web-server sh -c 'while true; do date >> /tmp/heartbeat.log; sleep 5; done'
# => Starts background process inside container
# => Returns immediately (detached)

# Check background process output
docker exec web-server tail -5 /tmp/heartbeat.log
# => Sun Dec 29 10:30:15 UTC 2025
# => Sun Dec 29 10:30:20 UTC 2025
# => Shows last 5 entries

# Run container with single port mapping
docker run -d --name web1 -p 8080:80 nginx:alpine
# => Maps host port 8080 to container port 80 (TCP default)
# => Accessible at http://localhost:8080

# Run with specific host IP
docker run -d --name web2 -p 127.0.0.1:8081:80 nginx:alpine
# => Only accessible from localhost (not external network)
# => Accessible at http://127.0.0.1:8081

# Run with random host port
docker run -d --name web3 -p 80 nginx:alpine
# => Docker assigns random available host port
# => Check with: docker port web3

docker port web3
# => 80/tcp -> 0.0.0.0:32768
# => Host port 32768 mapped to container port 80

# Map multiple ports
docker run -d --name app \
  -p 8080:80 \
  -p 8443:443 \
  nginx:alpine
# => HTTP on 8080, HTTPS on 8443

# Map UDP port
docker run -d --name dns-server -p 53:53/udp my-dns-image
# => Maps UDP port 53
# => Requires /udp suffix (default is /tcp)

# Map both TCP and UDP for same port
docker run -d --name multi-protocol \
  -p 8080:8080/tcp \
  -p 8080:8080/udp \
  my-app
# => Same port number, different protocols

# Expose all EXPOSE'd ports with random host ports
docker run -d --name auto-ports -P nginx:alpine
# => -P (capital P) publishes all EXPOSE'd ports
# => Docker assigns random host ports

docker port auto-ports
# => 80/tcp -> 0.0.0.0:32769
# => Shows automatically assigned port

# Check port mapping for running container
docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}}{{$p}} -> {{(index $conf 0).HostPort}}{{println}}{{end}}' web1
# => 80/tcp -> 8080

# Test connection from host
curl http://localhost:8080
# => Output: <!DOCTYPE html>... (nginx welcome page)

# View network connections
netstat -tlnp | grep 8080
# => tcp6    0    0 :::8080    :::*    LISTEN    1234/docker-proxy
# => Shows docker-proxy listening on port 8080

# Create named volume explicitly
docker volume create my-data
# => my-data
# => Creates volume in /var/lib/docker/volumes/

# List volumes
docker volume ls
# => DRIVER    VOLUME NAME
# => local     my-data

# Inspect volume details
docker volume inspect my-data
# => [
# =>   {
# =>     "CreatedAt": "2025-12-29T10:30:00Z",
# =>     "Driver": "local",
# =>     "Mountpoint": "/var/lib/docker/volumes/my-data/_data",
# =>     "Name": "my-data",
# =>     "Scope": "local"
# =>   }
# => ]

# Run container with named volume
docker run -d --name db \
  -v my-data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret \
  postgres:15-alpine
# => Mounts my-data volume to /var/lib/postgresql/data
# => Database files persist in volume

# Write data to database (survives container removal)
docker exec -it db psql -U postgres -c "CREATE DATABASE testdb;"
# => CREATE DATABASE
# => Data written to volume

# Stop and remove container
docker stop db
docker rm db
# => Container removed but volume persists

# Create new container with same volume
docker run -d --name db2 \
  -v my-data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret \
  postgres:15-alpine
# => Uses existing volume with data intact

# Verify data persisted
docker exec -it db2 psql -U postgres -c "\l"
# => Output includes: testdb | postgres | UTF8 | ...
# => Database from previous container still exists!

# Create volume with auto-creation (no explicit volume create)
docker run -d --name app \
  -v app-logs:/var/log/app \
  my-app-image
# => Docker creates app-logs volume automatically if it doesn't exist

# Share volume between containers
docker run -d --name writer \
  -v shared:/data \
  alpine sh -c 'while true; do date >> /data/log.txt; sleep 5; done'
# => Writes timestamps to /data/log.txt in volume

docker run -d --name reader \
  -v shared:/input:ro \
  alpine sh -c 'while true; do tail -1 /input/log.txt; sleep 5; done'
# => Reads from same volume (read-only mount with :ro)

# Check reader output
docker logs -f reader
# => Sun Dec 29 10:35:00 UTC 2025
# => Sun Dec 29 10:35:05 UTC 2025
# => Shows timestamps written by writer container

# Remove volume (only when no containers use it)
docker stop writer reader
docker rm writer reader
docker volume rm shared
# => Deletes volume and all data
# => Cannot remove volume while in use

# Prepare application files on host
mkdir -p ~/myapp
cd ~/myapp

cat > server.js << 'EOF'
const http = require('http');
const fs = require('fs');

const server = http.createServer((req, res) => {
  // Read message from file (can be updated on host)
  const message = fs.readFileSync('/app/message.txt', 'utf8');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end(message);
});

server.listen(3000, () => {
  console.log('Server listening on port 3000');
});
EOF
# => Creates server.js in current directory

echo "Hello from bind mount!" > message.txt
# => Creates message.txt with initial content

cat > package.json << 'EOF'
{
  "name": "bind-mount-demo",
  "version": "1.0.0",
  "main": "server.js"
}
EOF
# => Creates package.json

# Run container with bind mount (absolute path required)
docker run -d --name dev-app \
  -v "$(pwd)":/app \
  -w /app \
  -p 3000:3000 \
  node:18-alpine \
  node server.js
# => Mounts current directory to /app in container
# => $(pwd) expands to absolute path (required for -v)
# => -w sets working directory to /app

# Test initial response
curl http://localhost:3000
# => Output: Hello from bind mount!

# Update message.txt on host (WITHOUT restarting container)
echo "Updated message!" > message.txt
# => Changes file on host filesystem

# Test updated response (no container restart needed!)
curl http://localhost:3000
# => Output: Updated message!
# => Container reads updated file immediately

# Bind mount with read-only access
docker run -d --name readonly-app \
  -v "$(pwd)":/app:ro \
  -w /app \
  -p 3001:3000 \
  node:18-alpine \
  node server.js
# => :ro makes bind mount read-only
# => Container cannot modify host files

# Try to write from container (fails with read-only mount)
docker exec readonly-app sh -c 'echo "test" > /app/test.txt'
# => sh: can't create /app/test.txt: Read-only file system
# => Write operation denied

# Bind mount with specific user permissions
docker run -d --name owned-app \
  -v "$(pwd)":/app \
  -w /app \
  -u $(id -u):$(id -g) \
  -p 3002:3000 \
  node:18-alpine \
  node server.js
# => Runs container as current user (not root)
# => Files created in container have host user ownership

# Clean up
docker stop dev-app readonly-app owned-app
docker rm dev-app readonly-app owned-app

# Run container with tmpfs mount
docker run -d --name temp-app \
  --tmpfs /tmp:rw,size=100m,mode=1777 \
  -p 3000:3000 \
  node:18-alpine \
  sh -c 'while true; do echo "Data: $(date)" > /tmp/cache.txt; sleep 2; done'
# => Creates tmpfs mount at /tmp with 100MB limit
# => rw: read-write access
# => size=100m: maximum size 100 megabytes
# => mode=1777: permissions (sticky bit + rwxrwxrwx)

# Verify tmpfs mount inside container
docker exec temp-app df -h /tmp
# => Filesystem      Size  Used  Avail  Use%  Mounted on
# => tmpfs           100M  4.0K  100M    1%   /tmp
# => Shows tmpfs mount with 100MB size limit

# Write data to tmpfs
docker exec temp-app sh -c 'dd if=/dev/zero of=/tmp/testfile bs=1M count=10'
# => 10+0 records in
# => 10+0 records out
# => Writes 10MB to tmpfs (stored in RAM, not disk)

docker exec temp-app du -sh /tmp/testfile
# => 10.0M   /tmp/testfile

# Verify data exists in memory
docker exec temp-app cat /tmp/cache.txt
# => Data: Sun Dec 29 10:40:15 UTC 2025
# => Data stored in RAM

# Stop and restart container (tmpfs data is LOST)
docker stop temp-app
docker start temp-app

# Check if data persists (it doesn't!)
docker exec temp-app ls /tmp/
# => Empty output or only new files
# => All previous tmpfs data lost on container stop

# Use case: Sensitive credential caching
docker run -d --name secure-app \
  --tmpfs /run/secrets:rw,size=10m,mode=0700 \
  alpine sh -c 'echo "secret-token" > /run/secrets/token; while true; do sleep 3600; done'
# => Stores secrets in memory only
# => mode=0700: only owner can read/write (more restrictive)

docker exec secure-app cat /run/secrets/token
# => Output: secret-token
# => Data never written to disk

# Multiple tmpfs mounts
docker run -d --name multi-tmp \
  --tmpfs /tmp:size=100m \
  --tmpfs /var/cache:size=50m \
  --tmpfs /var/log:size=50m \
  alpine sleep 3600
# => Multiple tmpfs mounts in single container
# => Different size limits for different purposes

# Verify all tmpfs mounts
docker exec multi-tmp df -h
# => tmpfs     100M     0   100M   0%  /tmp
# => tmpfs      50M     0    50M   0%  /var/cache
# => tmpfs      50M     0    50M   0%  /var/log

# Create custom bridge network
docker network create my-bridge
# => Network ID: abc123def456789...
# => Creates isolated bridge network

# List networks
docker network ls
# => NETWORK ID     NAME         DRIVER    SCOPE
# => abc123def456   my-bridge    bridge    local
# => def456ghi789   bridge       bridge    local (default)
# => ghi789jkl012   host         host      local
# => jkl012mno345   none         null      local

# Inspect network details
docker network inspect my-bridge
# => [
# =>   {
# =>     "Name": "my-bridge",
# =>     "Driver": "bridge",
# =>     "Subnet": "172.18.0.0/16",
# =>     "Gateway": "172.18.0.1",
# =>     "Containers": {}
# =>   }
# => ]

# Run database on custom bridge
docker run -d --name postgres-db \
  --network my-bridge \
  -e POSTGRES_PASSWORD=secret \
  postgres:15-alpine
# => Container gets IP on my-bridge network
# => Accessible by name "postgres-db" within network

# Run API server on same network
docker run -d --name api-server \
  --network my-bridge \
  -p 8080:8080 \
  -e DB_HOST=postgres-db \
  -e DB_PASSWORD=secret \
  my-api-image
# => Can connect to database using hostname "postgres-db"
# => Docker's built-in DNS resolves container names

# Test DNS resolution from api-server
docker exec api-server nslookup postgres-db
# => Server:    127.0.0.11 (Docker's embedded DNS server)
# => Name:      postgres-db
# => Address:   172.18.0.2 (container IP on my-bridge)

# Test connectivity between containers
docker exec api-server ping -c 2 postgres-db
# => PING postgres-db (172.18.0.2): 56 data bytes
# => 64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.123 ms
# => 64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.098 ms
# => Containers can ping each other by name

# Connect existing container to additional network
docker network connect my-bridge some-existing-container
# => Container now connected to both original and my-bridge networks
# => Can communicate with containers on both networks

# Disconnect container from network
docker network disconnect my-bridge some-existing-container
# => Removes container from my-bridge network

# Run container on default bridge (no automatic DNS)
docker run -d --name old-style-db postgres:15-alpine
# => Runs on default bridge network
# => Other containers on default bridge CANNOT use name-based DNS

# Containers on default bridge need IP addresses or links (legacy)
docker inspect old-style-db --format='{{.NetworkSettings.IPAddress}}'
# => 172.17.0.2 (must use IP address, not name)

# Remove network (only when no containers attached)
docker network rm my-bridge
# => Error: network my-bridge has active endpoints
# => Must stop/remove containers first

# Create application network
docker network create app-network
# => Network for frontend, backend, database

# Start PostgreSQL database
docker run -d --name database \
  --network app-network \
  -e POSTGRES_USER=appuser \
  -e POSTGRES_PASSWORD=apppass \
  -e POSTGRES_DB=appdb \
  postgres:15-alpine
# => Database accessible at hostname "database"

# Start Node.js backend API
cat > backend.js << 'EOF'
const express = require('express');
const { Pool } = require('pg');

const pool = new Pool({
  host: 'database',              // Container name as hostname
  user: 'appuser',
  password: 'apppass',
  database: 'appdb',
  port: 5432,
});

const app = express();

app.get('/api/status', async (req, res) => {
  try {
    const result = await pool.query('SELECT NOW()');
    res.json({
      status: 'ok',
      database_time: result.rows[0].now,
    });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.listen(3000, () => {
  console.log('Backend API listening on port 3000');
});
EOF
# => Backend connects to database using "database" hostname

docker build -t my-backend -f- . << 'EOF'
FROM node:18-alpine
WORKDIR /app
RUN npm install express pg
COPY backend.js .
CMD ["node", "backend.js"]
EOF
# => Builds backend image

docker run -d --name backend \
  --network app-network \
  my-backend
# => Backend can resolve "database" hostname
# => Not exposing port yet (internal only)

# Test backend to database connection
docker exec backend wget -qO- http://localhost:3000/api/status
# => {"status":"ok","database_time":"2025-12-29T10:45:00.123Z"}
# => Backend successfully connects to database

# Start Nginx frontend
cat > nginx.conf << 'EOF'
server {
    listen 80;
    location /api/ {
        proxy_pass http://backend:3000/api/;  # Container name as hostname
    }
    location / {
        return 200 'Frontend served by Nginx\n';
        add_header Content-Type text/plain;
    }
}
EOF

docker run -d --name frontend \
  --network app-network \
  -p 8080:80 \
  -v "$(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro" \
  nginx:alpine
# => Frontend proxies /api/ requests to backend:3000
# => Uses container name "backend" in nginx config

# Test full stack: frontend -> backend -> database
curl http://localhost:8080/api/status
# => {"status":"ok","database_time":"2025-12-29T10:45:00.123Z"}
# => Request flows: host -> frontend -> backend -> database

# Verify DNS resolution inside containers
docker exec frontend nslookup backend
# => Server:    127.0.0.11 (Docker DNS)
# => Name:      backend
# => Address:   172.19.0.3

docker exec backend nslookup database
# => Server:    127.0.0.11
# => Name:      database
# => Address:   172.19.0.2

# Check network connectivity between containers
docker exec frontend ping -c 1 backend
# => 64 bytes from 172.19.0.3: seq=0 ttl=64 time=0.123 ms

docker exec backend ping -c 1 database
# => 64 bytes from 172.19.0.2: seq=0 ttl=64 time=0.089 ms

# Inspect network to see all connected containers
docker network inspect app-network --format='{{range .Containers}}{{.Name}}: {{.IPv4Address}}{{"\n"}}{{end}}'
# => database: 172.19.0.2/16
# => backend: 172.19.0.3/16
# => frontend: 172.19.0.4/16

# Create environment variable file
cat > database.env << 'EOF'
POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword
POSTGRES_DB=mydb
POSTGRES_HOST_AUTH_METHOD=scram-sha-256
EOF
# => Stores database configuration in file

cat > app.env << 'EOF'
NODE_ENV=production
LOG_LEVEL=info
API_KEY=secret-key-12345
DATABASE_URL=postgresql://myuser:mypassword@db:5432/mydb
EOF
# => Stores application configuration in file

# Start database with env file
docker run -d --name db \
  --env-file database.env \
  --network app-net \
  postgres:15-alpine
# => Loads all variables from database.env
# => Equivalent to multiple -e flags

# Verify environment variables loaded
docker exec db printenv | grep POSTGRES
# => POSTGRES_USER=myuser
# => POSTGRES_PASSWORD=mypassword
# => POSTGRES_DB=mydb
# => POSTGRES_HOST_AUTH_METHOD=scram-sha-256

# Start application with env file
docker run -d --name app \
  --env-file app.env \
  --network app-net \
  -p 3000:3000 \
  my-app-image
# => Loads all variables from app.env

# Override specific variables while using env file
docker run -d --name app-dev \
  --env-file app.env \
  -e NODE_ENV=development \
  -e LOG_LEVEL=debug \
  --network app-net \
  -p 3001:3000 \
  my-app-image
# => Loads app.env, then overrides NODE_ENV and LOG_LEVEL
# => -e flag takes precedence over --env-file

# Use multiple env files
docker run -d --name app-multi \
  --env-file common.env \
  --env-file production.env \
  my-app-image
# => Loads variables from both files
# => Later files override earlier ones if keys conflict

# Template env file for documentation
cat > .env.example << 'EOF'
# Database Configuration
POSTGRES_USER=changeme
POSTGRES_PASSWORD=changeme
POSTGRES_DB=mydb

# Application Configuration
NODE_ENV=production
LOG_LEVEL=info
API_KEY=your-api-key-here

# Feature Flags
ENABLE_CACHE=true
ENABLE_METRICS=false
EOF
# => Template for developers (commit to version control)
# => Actual .env file (with secrets) goes in .gitignore

# Create .gitignore to prevent committing secrets
cat > .gitignore << 'EOF'
*.env
!.env.example
EOF
# => Prevents committing actual .env files
# => Allows committing .env.example template

# Inspect container to view environment variables
docker inspect app --format='{{range .Config.Env}}{{println .}}{{end}}'
# => NODE_ENV=production
# => LOG_LEVEL=info
# => API_KEY=secret-key-12345
# => DATABASE_URL=postgresql://myuser:mypassword@db:5432/mydb
# => Shows all environment variables (CAREFUL: exposes secrets!)

# File: docker-compose.yml

version: "3.8"
# => Compose file format version (3.8 is widely compatible)

services:
  # Database service
  db:
    image: postgres:15-alpine
    # => Uses official PostgreSQL 15 image
    container_name: my-postgres
    # => Custom container name (default: project_db_1)
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: apppass
      POSTGRES_DB: appdb
      # => Environment variables passed to container
    volumes:
      - db-data:/var/lib/postgresql/data
      # => Named volume for database persistence
    networks:
      - backend
      # => Connects to backend network
    restart: unless-stopped
    # => Restart policy: always restart unless explicitly stopped

  # Backend API service
  api:
    build:
      context: ./api
      dockerfile: Dockerfile
      # => Builds image from ./api/Dockerfile
    container_name: my-api
    environment:
      DATABASE_URL: postgresql://appuser:apppass@db:5432/appdb
      # => Database connection using service name "db"
    depends_on:
      - db
      # => Ensures db starts before api
      # => NOTE: Does NOT wait for db to be ready, only started
    networks:
      - backend
      - frontend
      # => Connects to both networks for db and web communication
    restart: unless-stopped

  # Web frontend service
  web:
    image: nginx:alpine
    # => Uses official Nginx alpine image
    container_name: my-web
    ports:
      - "8080:80"
      # => Maps host port 8080 to container port 80
    volumes:
      - ./web/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      # => Mounts nginx config as read-only
      - ./web/html:/usr/share/nginx/html:ro
      # => Mounts static files as read-only
    depends_on:
      - api
      # => Ensures api starts before web
    networks:
      - frontend
      # => Connects only to frontend network (no direct db access)
    restart: unless-stopped

networks:
  frontend:
    driver: bridge
    # => Custom bridge network for frontend services
  backend:
    driver: bridge
    # => Custom bridge network for backend services
    # => Separates frontend and backend layers

volumes:
  db-data:
    # => Named volume managed by Docker
    # => Persists database data across container recreations

# Start all services defined in docker-compose.yml
docker compose up -d
# => Creates networks: project_frontend, project_backend
# => Creates volume: project_db-data
# => Starts containers: my-postgres, my-api, my-web
# => -d runs in detached mode (background)

# View running services
docker compose ps
# => NAME          IMAGE              STATUS        PORTS
# => my-postgres   postgres:15-alpine Up 30 seconds
# => my-api        project_api        Up 25 seconds
# => my-web        nginx:alpine       Up 20 seconds 0.0.0.0:8080->80/tcp

# View logs from all services
docker compose logs
# => Shows combined logs from all services
# => Color-coded by service

# View logs from specific service
docker compose logs -f api
# => Follows logs from api service only
# => -f streams logs in real-time

# Stop all services (keeps containers)
docker compose stop
# => Stops all containers without removing them

# Start stopped services
docker compose start
# => Starts previously stopped containers

# Restart specific service
docker compose restart api
# => Stops and starts api service

# Stop and remove all services, networks (keeps volumes)
docker compose down
# => Removes containers and networks
# => Preserves named volumes (db-data persists)

# Remove everything including volumes (DESTRUCTIVE)
docker compose down -v
# => Removes containers, networks, AND volumes
# => Database data is deleted!

# Rebuild images and restart services
docker compose up -d --build
# => Rebuilds images before starting
# => Useful after code changes

# Scale a service (create multiple instances)
docker compose up -d --scale api=3
# => Creates 3 instances of api service
# => Requires removing container_name (generates unique names)

# Execute command in running service
docker compose exec api sh
# => Opens shell in api service container
# => Similar to docker exec

# View service configuration
docker compose config
# => Shows resolved configuration (interpolated variables, defaults)

# File: docker-compose.yml

version: "3.8"

services:
  app:
    build:
      context: .
      # => Build context is current directory
      # => All files in this directory available to COPY/ADD
      dockerfile: Dockerfile.prod
      # => Uses Dockerfile.prod instead of default Dockerfile
      args:
        - NODE_VERSION=18
        - BUILD_DATE=2025-12-29
        # => Build arguments passed to Dockerfile
      target: production
      # => Builds only up to "production" stage (multi-stage builds)
    image: my-app:latest
    # => Tags built image as my-app:latest
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production

  dev-app:
    build:
      context: .
      dockerfile: Dockerfile.prod
      args:
        NODE_VERSION: 18
      target: development
      # => Builds development stage from same Dockerfile
    image: my-app:dev
    # => Different image tag for development
    volumes:
      - .:/app
      # => Bind mount for live code reloading
    ports:
      - "3001:3000"
    environment:
      NODE_ENV: development

# File: Dockerfile.prod

ARG NODE_VERSION=18
# => Build argument for Node.js version

FROM node:${NODE_VERSION}-alpine as base
# => Uses build arg in FROM instruction
# => Names stage as "base"

WORKDIR /app
COPY package*.json ./

# Development stage
FROM base as development
# => Inherits from base stage
RUN npm install
# => Installs all dependencies (including devDependencies)
COPY . .
EXPOSE 3000
CMD ["npm", "run", "dev"]
# => Development command with hot reloading

# Production stage
FROM base as production
# => Inherits from base stage (NOT development)
RUN npm ci --only=production
# => Installs only production dependencies
COPY . .
RUN npm run build
# => Builds optimized production bundle
EXPOSE 3000
CMD ["npm", "start"]
# => Production startup command

# Build information label
ARG BUILD_DATE
LABEL build_date=${BUILD_DATE}
# => Adds build date to image metadata

# Build and start production service
docker compose up -d app
# => Builds image using production target
# => Tags as my-app:latest
# => Starts container in production mode

# Build and start development service
docker compose up -d dev-app
# => Builds image using development target
# => Tags as my-app:dev
# => Starts container with bind mount for live reloading

# Rebuild images (force, ignore cache)
docker compose build --no-cache
# => Rebuilds all services from scratch
# => Useful when dependencies change

# Build specific service
docker compose build app
# => Rebuilds only app service image

# Build with different build args
docker compose build --build-arg NODE_VERSION=20 app
# => Overrides NODE_VERSION build argument
# => Uses Node.js 20 instead of default 18

# View build output
docker compose build app --progress=plain
# => Shows full build output (not condensed)
# => Useful for debugging build issues

# Pull base images before building
docker compose build --pull app
# => Pulls latest base image (node:18-alpine)
# => Ensures base image is up-to-date before building

# Build and push to registry
docker compose build app
docker compose push app
# => Builds image and pushes to Docker registry
# => Requires image name to be fully qualified (registry/image:tag)

# File: docker-compose.yml

version: "3.8"

services:
  app:
    image: my-app:latest
    environment:
      # Method 1: Inline key-value pairs
      NODE_ENV: production
      LOG_LEVEL: info
      # Method 2: Value from .env file or host environment
      DATABASE_URL:
      # => If no value specified, reads from .env or host
      # Method 3: Default value with substitution
      API_TIMEOUT: ${API_TIMEOUT:-5000}
      # => Uses API_TIMEOUT from .env, or defaults to 5000
      PORT: ${PORT:-3000}
      # => Uses PORT from .env, or defaults to 3000
    env_file:
      - .env
      - .env.local
      # => Loads variables from files (later files override earlier)
    ports:
      - "${PORT:-3000}:3000"
      # => Port mapping uses variable substitution

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME:-myapp}
      # => Required variables (fail if not set)
    env_file:
      - database.env
      # => Additional database-specific variables

# File: .env (automatically loaded by Docker Compose)
DATABASE_URL=postgresql://user:pass@db:5432/myapp
API_TIMEOUT=10000
PORT=8080
DB_USER=appuser
DB_PASSWORD=secret123
DB_NAME=production_db

# File: .env.local (overrides .env values)
LOG_LEVEL=debug
PORT=8081

# Start services with .env files
docker compose up -d
# => Reads .env automatically (no flag needed)
# => Also reads .env.local (specified in env_file)
# => Variables: DATABASE_URL, API_TIMEOUT=10000, PORT=8081 (from .env.local)

# Verify environment variables in container
docker compose exec app printenv | grep -E "DATABASE_URL|API_TIMEOUT|PORT"
# => DATABASE_URL=postgresql://user:pass@db:5432/myapp
# => API_TIMEOUT=10000
# => PORT=8081 (overridden by .env.local)

# Override variables from command line
PORT=9000 docker compose up -d
# => Host environment variable overrides .env and .env.local
# => App runs on port 9000

# Override with docker compose run
docker compose run -e LOG_LEVEL=trace app npm test
# => Overrides LOG_LEVEL for this specific run
# => Other variables still loaded from .env files

# Check variable substitution
docker compose config
# => Shows resolved configuration with all variables substituted
# => Useful for debugging variable precedence

# Example output of docker compose config:
# => services:
# =>   app:
# =>     environment:
# =>       NODE_ENV: production
# =>       LOG_LEVEL: debug (from .env.local)
# =>       DATABASE_URL: postgresql://user:pass@db:5432/myapp
# =>       API_TIMEOUT: 10000
# =>       PORT: 8081
# =>     ports:
# =>       - "8081:3000"

# Test with missing required variable
unset DB_PASSWORD
docker compose up -d
# => Error: environment variable DB_PASSWORD is not set
# => Compose fails when required variable (no default) is missing

# File: docker-compose.yml

version: "3.8"

services:
  # Database with named volume
  db:
    image: postgres:15-alpine
    volumes:
      - db-data:/var/lib/postgresql/data
      # => Named volume (defined in volumes section)
      # => Managed by Docker, persists across recreations
    environment:
      POSTGRES_PASSWORD: secret

  # Application with multiple volume types
  app:
    build: .
    volumes:
      # Bind mount for source code (development)
      - ./src:/app/src:ro
      # => Host ./src directory mounted as read-only
      # => Changes on host immediately visible in container

      # Bind mount for configuration
      - ./config/app.conf:/etc/app/app.conf:ro
      # => Single file bind mount

      # Named volume for generated assets
      - app-cache:/app/.cache
      # => Persists compiled assets across rebuilds

      # Tmpfs for temporary processing
      - type: tmpfs
        target: /tmp
        tmpfs:
          size: 100M
      # => RAM-based temporary storage
    depends_on:
      - db

  # Nginx with bind mount for static content
  web:
    image: nginx:alpine
    volumes:
      - ./web/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      # => Nginx configuration
      - ./web/html:/usr/share/nginx/html:ro
      # => Static HTML files
      - web-logs:/var/log/nginx
      # => Named volume for log persistence
    ports:
      - "8080:80"

# Named volumes definition
volumes:
  db-data:
    driver: local
    # => Default driver (stores on host filesystem)
  app-cache:
    driver: local
  web-logs:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /var/log/myapp/web
      # => Custom mount options (advanced)

# Start services (creates volumes automatically)
docker compose up -d
# => Creates named volumes: project_db-data, project_app-cache, project_web-logs
# => Bind mounts connect to host directories

# List volumes created by Compose
docker volume ls --filter label=com.docker.compose.project=myproject
# => DRIVER    VOLUME NAME
# => local     myproject_db-data
# => local     myproject_app-cache
# => local     myproject_web-logs

# Inspect named volume
docker volume inspect myproject_db-data
# => [
# =>   {
# =>     "Name": "myproject_db-data",
# =>     "Driver": "local",
# =>     "Mountpoint": "/var/lib/docker/volumes/myproject_db-data/_data",
# =>     "Labels": {
# =>       "com.docker.compose.project": "myproject",
# =>       "com.docker.compose.version": "2.20.0",
# =>       "com.docker.compose.volume": "db-data"
# =>     }
# =>   }
# => ]

# Write data to database (persists in named volume)
docker compose exec db psql -U postgres -c "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT);"
# => CREATE TABLE

# Stop and remove containers (preserves named volumes)
docker compose down
# => Removes containers but keeps volumes

# Start again (data still exists in volumes)
docker compose up -d

# Verify data persisted
docker compose exec db psql -U postgres -c "SELECT * FROM users;"
# => id | name
# => ----+------
# => (0 rows)
# => Table still exists (volume preserved)

# Update bind-mounted file on host (reflects immediately in container)
echo "Updated content" >> ./web/html/index.html
docker compose exec web cat /usr/share/nginx/html/index.html
# => Shows updated content immediately (no restart needed)

# Backup named volume
docker run --rm \
  -v myproject_db-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/db-backup.tar.gz /data
# => Creates tar archive of volume contents

# Restore named volume
docker run --rm \
  -v myproject_db-data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/db-backup.tar.gz -C /
# => Extracts tar archive to volume

# Remove volumes with containers
docker compose down -v
# => Removes containers AND named volumes (DESTRUCTIVE!)
# => Use for complete cleanup

# File: docker-compose.yml

version: "3.8"

services:
  # Database service
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: apppass
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser"]
      # => Checks if PostgreSQL accepts connections
      interval: 5s
      # => Run check every 5 seconds
      timeout: 3s
      # => Fail check if it takes longer than 3 seconds
      retries: 3
      # => Mark unhealthy after 3 consecutive failures
      start_period: 10s
      # => Grace period before checking (allows startup time)

  # Redis cache
  cache:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      # => Checks if Redis responds to PING
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 5s

  # API service (basic depends_on)
  api-basic:
    build: ./api
    depends_on:
      - db
      - cache
      # => Starts db and cache BEFORE api-basic
      # => Does NOT wait for db/cache to be ready
      # => API may crash if it connects before db is ready
    environment:
      DATABASE_URL: postgresql://appuser:apppass@db:5432/appdb
      REDIS_URL: redis://cache:6379

  # API service (depends_on with health checks)
  api-healthy:
    build: ./api
    depends_on:
      db:
        condition: service_healthy
        # => Waits for db health check to pass
      cache:
        condition: service_healthy
        # => Waits for cache health check to pass
    environment:
      DATABASE_URL: postgresql://appuser:apppass@db:5432/appdb
      REDIS_URL: redis://cache:6379
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      # => Checks API /health endpoint
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s
      # => Longer start_period for API initialization

  # Web frontend (depends on healthy API)
  web:
    image: nginx:alpine
    depends_on:
      api-healthy:
        condition: service_healthy
        # => Waits for API to be healthy before starting
    ports:
      - "8080:80"
    volumes:
      - ./web/nginx.conf:/etc/nginx/conf.d/default.conf:ro

# Start services (observe startup order)
docker compose up -d
# => Step 1: Starts db and cache (no dependencies)
# => Step 2: Waits for db and cache health checks to pass
# => Step 3: Starts api-basic (doesn't wait for health) and api-healthy (waits for health)
# => Step 4: Waits for api-healthy health check to pass
# => Step 5: Starts web (after api-healthy is healthy)

# Monitor service health status
docker compose ps
# => NAME      STATUS                    HEALTH
# => db        Up 30 seconds             healthy
# => cache     Up 30 seconds             healthy
# => api-basic Up 25 seconds             (no health check)
# => api-healthy Up 20 seconds           starting (health: starting)
# => web       Created                   (waiting for api-healthy)

# Wait a bit for health checks
sleep 30
docker compose ps
# => NAME      STATUS                    HEALTH
# => db        Up 1 minute               healthy
# => cache     Up 1 minute               healthy
# => api-basic Up 55 seconds             (no health check)
# => api-healthy Up 50 seconds           healthy
# => web       Up 20 seconds             (no health check)

# View health check logs
docker inspect myproject-db-1 --format='{{json .State.Health}}' | jq
# => {
# =>   "Status": "healthy",
# =>   "FailingStreak": 0,
# =>   "Log": [
# =>     {
# =>       "Start": "2025-12-29T10:50:00Z",
# =>       "End": "2025-12-29T10:50:00Z",
# =>       "ExitCode": 0,
# =>       "Output": "accepting connections"
# =>     }
# =>   ]
# => }

# Test difference between basic and healthy depends_on
docker compose restart db
# => Restarts database

# api-basic may crash immediately (connects before db ready)
docker compose logs api-basic
# => Error: connection refused (database not ready)

# api-healthy waits for db to become healthy again
docker compose ps api-healthy
# => STATUS: Up (health: starting) - waiting for db to be healthy

# File: docker-compose.yml

version: "3.8"

services:
  # Public-facing web server (frontend network only)
  web:
    image: nginx:alpine
    networks:
      - frontend
      # => Only connected to frontend network
      # => Cannot directly access database
    ports:
      - "8080:80"

  # API application (both networks)
  api:
    build: ./api
    networks:
      - frontend
      # => Can communicate with web
      - backend
      # => Can communicate with database
    environment:
      DATABASE_URL: postgresql://user:pass@db:5432/mydb

  # Database (backend network only)
  db:
    image: postgres:15-alpine
    networks:
      - backend
      # => Only connected to backend network
      # => Not accessible from web (network isolation)
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: mydb

  # Admin tool (backend network only)
  admin:
    image: dpage/pgadmin4
    networks:
      - backend
      # => Can access database directly
    ports:
      - "5050:80"
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@example.com
      PGADMIN_DEFAULT_PASSWORD: admin

networks:
  frontend:
    driver: bridge
    # => Network for public-facing services
  backend:
    driver: bridge
    # => Network for backend services
    internal: true
    # => Internal-only network (no external internet access)

# Start services with network segmentation
docker compose up -d
# => Creates networks: myproject_frontend, myproject_backend

# List networks
docker network ls --filter label=com.docker.compose.project=myproject
# => NETWORK ID     NAME                  DRIVER    SCOPE
# => abc123def456   myproject_frontend    bridge    local
# => def456ghi789   myproject_backend     bridge    local

# Verify web cannot access db directly (different networks)
docker compose exec web ping -c 1 db
# => ping: bad address 'db'
# => Name resolution fails (not on same network)

# Verify api can access both web and db (on both networks)
docker compose exec api ping -c 1 web
# => 64 bytes from 172.20.0.2: seq=0 ttl=64 time=0.123 ms
# => Success (both on frontend network)

docker compose exec api ping -c 1 db
# => 64 bytes from 172.21.0.2: seq=0 ttl=64 time=0.089 ms
# => Success (both on backend network)

# Verify admin can access db (same backend network)
docker compose exec admin ping -c 1 db
# => 64 bytes from 172.21.0.2: seq=0 ttl=64 time=0.095 ms

# Inspect network to see connected services
docker network inspect myproject_frontend --format='{{range .Containers}}{{.Name}}{{"\n"}}{{end}}'
# => myproject-web-1
# => myproject-api-1
# => Only web and api on frontend network

docker network inspect myproject_backend --format='{{range .Containers}}{{.Name}}{{"\n"}}{{end}}'
# => myproject-api-1
# => myproject-db-1
# => myproject-admin-1
# => Only api, db, and admin on backend network

# Create external network (shared across projects)
docker network create shared-network
# => Network exists outside Compose project

# Use external network in compose file
cat >> docker-compose.yml << 'EOF'
  external-service:
    image: my-service
    networks:
      - shared-network

networks:
  shared-network:
    external: true
    # => References existing network (doesn't create new one)
EOF

docker compose up -d external-service
# => Uses existing shared-network