#Docker Usage Guide

This document collects practical Docker commands you can use in daily development and troubleshooting. It starts with the basics and then moves into more advanced but still broadly useful commands.

#Core Concepts

• Image: A read-only template used to create containers.
• Container: A running or stopped instance of an image.
• Volume: Persistent storage managed by Docker.
• Network: A virtual network used for container-to-container or host-to-container communication.

#Basic Commands

#Check Docker Version and Info

docker --version
docker version
docker info

• docker --version shows the installed CLI version.
• docker version shows both client and server versions.
• docker info shows engine details, storage driver, container count, and more.

#Search and Download Images

docker search nginx
docker pull nginx
docker pull node:20-alpine

• Use search to discover images on Docker Hub.
• Use pull to download a specific image and tag.

#List Local Images

docker images
docker image ls

#Run a Container

docker run nginx
docker run -d nginx
docker run -d -p 8080:80 --name web nginx

• -d runs the container in detached mode.
• -p 8080:80 maps host port 8080 to container port 80.
• --name web gives the container a readable name.

#List Running and All Containers

docker ps
docker ps -a
docker container ls
docker container ls -a

#Stop, Start, Restart, Remove

docker stop web
docker start web
docker restart web
docker rm web
docker rm -f web

• rm -f force removes a running container.

#Remove Images

docker rmi nginx
docker image rm nginx

#Interactive Usage

#Start a Shell in a New Container

docker run -it ubuntu bash
docker run -it alpine sh

• -it combines interactive and TTY modes.

#Open a Shell in an Existing Container

docker exec -it web sh
docker exec -it web bash

Use exec when the container is already running and you want to inspect or debug it.

#Logs and Monitoring

#View Container Logs

docker logs web
docker logs -f web
docker logs --tail 100 web
docker logs -f --tail 50 web

• -f follows live log output.
• --tail limits how many recent lines are shown.

#View Resource Usage

docker stats
docker stats web

This is useful for checking CPU, memory, network, and block I/O usage.

#Inspecting Containers and Images

#Detailed Inspection

docker inspect web
docker inspect nginx

This returns JSON with configuration, mounts, ports, IP address, and metadata.

#Useful Inspect Filters

docker inspect -f '{{.NetworkSettings.IPAddress}}' web
docker inspect -f '{{json .Mounts}}' web
docker inspect -f '{{.State.Status}}' web

These filtered templates are much faster than reading the full JSON output.

#View Port Mappings

docker port web

#Working with Files

#Copy Files Between Host and Container

docker cp ./local.txt web:/tmp/local.txt
docker cp web:/var/log/nginx/access.log ./access.log

#Mount a Host Directory

docker run -d -p 8080:80 -v $(pwd):/app node:20-alpine

This mounts the current host directory into /app inside the container.

#Volumes

#Create and List Volumes

docker volume create app_data
docker volume ls

#Use a Volume

docker run -d --name db -v app_data:/var/lib/mysql mysql:8

#Inspect and Remove Volumes

docker volume inspect app_data
docker volume rm app_data

Volumes are preferred over container-local storage when data must survive container recreation.

#Networks

#List and Create Networks

docker network ls
docker network create app_net

#Attach a Container to a Network

docker run -d --name api --network app_net nginx
docker network connect app_net web

#Inspect and Remove Networks

docker network inspect app_net
docker network rm app_net

Custom networks are useful when multiple containers need to communicate by container name.

#Building Images

#Build from a Dockerfile

docker build -t my-app .
docker build -t my-app:1.0 .
docker build -f Dockerfile.dev -t my-app:dev .

#Tag and Push Images

docker tag my-app:1.0 username/my-app:1.0
docker push username/my-app:1.0

#Advanced but Useful Commands

#Show Only Specific Fields with --format

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.Size}}'

This is very useful when you want readable CLI output without manual filtering.

#Filter Results

docker ps -a --filter "name=web"
docker images --filter "dangling=true"
docker volume ls --filter "name=app"

#Inspect Container Processes

docker top web

This helps when debugging containers that appear healthy but are not doing the expected work.

#See Container Changes

docker diff web

This shows filesystem changes inside a container since it was created.

#Commit a Container as an Image

docker commit web debug/web:snapshot

This is helpful for temporary debugging workflows, though rebuilding from a Dockerfile is usually better for long-term use.

#Save and Load Images

docker save -o my-app.tar my-app:1.0
docker load -i my-app.tar

Useful when moving images between environments without pulling from a registry.

#Export and Import Container Filesystems

docker export web -o web.tar
docker import web.tar imported-web:latest

Unlike save and load, this works with container filesystems instead of image layers.

#Run Commands in One-Off Containers

docker run --rm alpine ls -la
docker run --rm node:20-alpine node -v

• --rm removes the container automatically after the command finishes.

#Set Environment Variables

docker run -e NODE_ENV=production my-app
docker run --env-file .env my-app

#Run PostgreSQL with Environment Configuration

docker run -d \
  --name postgres-db \
  -e POSTGRES_DB=myapp \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_PASSWORD=mypassword \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql/data \
  postgres:16

This starts PostgreSQL with a database, user, password, port mapping, and a persistent volume.

Example using an environment file:

docker run -d \
  --name postgres-db \
  --env-file .env.postgres \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql/data \
  postgres:16

Example .env.postgres content:

POSTGRES_DB=myapp
POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword

Useful PostgreSQL follow-up commands:

docker logs -f postgres-db
docker exec -it postgres-db psql -U myuser -d myapp
docker exec -it postgres-db sh

If you want a temporary PostgreSQL container with no persisted data, remove the volume mount:

docker run -d \
  --name postgres-temp \
  -e POSTGRES_DB=myapp \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_PASSWORD=mypassword \
  -p 5432:5432 \
  postgres:16

#Limit CPU and Memory

docker run -d --memory="512m" --cpus="1.5" my-app

This is useful for testing behavior under constrained resources.

#Restart Policies

docker run -d --restart unless-stopped nginx
docker run -d --restart always nginx

This is practical for local servers and lightweight long-running services.

#Health Checks

docker run -d \
  --health-cmd="curl -f http://localhost || exit 1" \
  --health-interval=30s \
  --health-timeout=5s \
  --health-retries=3 \
  nginx

Health checks help detect containers that are running but not actually ready.

#Cleanup Commands

#Remove Stopped Containers

docker container prune

#Remove Unused Images

docker image prune
docker image prune -a

#Remove Unused Volumes

docker volume prune

#Remove Unused Networks

docker network prune

#Clean Everything Unused

docker system prune
docker system prune -a --volumes

Be careful with prune commands because they can remove data you still need.

#Remove All Containers Shown by docker ps -a

docker rm -f $(docker ps -aq)

This force-removes every container, including running ones.

#Remove All Containers and Related Artifacts

If you want to remove all containers and also delete unused images, volumes, networks, and build cache:

docker rm -f $(docker ps -aq)
docker system prune -a --volumes -f

If you want a more explicit cleanup flow:

docker rm -f $(docker ps -aq)
docker volume rm $(docker volume ls -q)
docker network prune -f
docker image prune -a -f
docker builder prune -a -f

Use the explicit version carefully. Removing all volumes deletes persisted database and application data.

#Safer Variant for Scripts

If there may be no containers or no volumes, this avoids command errors:

docker ps -aq | xargs -r docker rm -f
docker volume ls -q | xargs -r docker volume rm
docker system prune -a --volumes -f

#Docker Compose Essentials

If Docker Compose is available through the Docker CLI plugin:

docker compose up
docker compose up -d
docker compose down
docker compose ps
docker compose logs -f
docker compose exec app sh
docker compose build

These are the most commonly used commands for multi-container applications.

#Docker Watch

For most development workflows, Docker Watch is used through docker compose watch.

docker compose watch
docker compose watch app
docker compose watch --no-up
docker compose watch --dry-run

• docker compose watch watches the configured services for file changes.
• docker compose watch app watches only the app service.
• --no-up skips the initial build and startup step.
• --dry-run shows what would happen without applying changes.

Docker Watch is especially useful in development because it can sync changed files into the container or trigger a rebuild automatically.

Example compose.yml configuration:

services:
  app:
    build: .
    ports:
      - "3000:3000"
    command: npm run dev
    develop:
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - node_modules/
        - action: rebuild
          path: package.json

What this example does:

• Changes in the project folder are synced into /app in the container.
• Changes to package.json trigger an image rebuild.
• node_modules/ is ignored to avoid unnecessary sync noise.

Typical workflow:

docker compose up -d
docker compose watch

This is a good alternative to bind mounts when you want more controlled file sync behavior.

#Practical Troubleshooting Examples

#Check Why a Container Exits Immediately

docker ps -a
docker logs <container_name>
docker inspect -f '{{.State.ExitCode}}' <container_name>

#Check Network Reachability Between Containers

docker exec -it api sh
ping web

#Check Mounted Files

docker inspect -f '{{json .Mounts}}' web

#Check Real Startup Command

docker inspect -f '{{.Config.Cmd}}' web
docker inspect -f '{{.Config.Entrypoint}}' web

#Recommended Daily Commands

If you only remember a short set, these are the most useful in daily work:

docker ps -a
docker logs -f <container>
docker exec -it <container> sh
docker inspect <container>
docker build -t my-app .
docker run -d -p 8080:80 --name my-app my-app
docker compose up -d
docker system prune

#Notes

• Prefer named containers for easier management.
• Prefer volumes for persistent data.
• Prefer --rm for short-lived utility containers.
• Use inspect, logs, and exec first when debugging.
• Use prune commands carefully in environments with important local data.