Docker CLI

What it is

Docker CLI is the command-line interface for interacting with the Docker engine, used to build, run, and manage containerized applications.

Installation

Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Linux (Fedora):

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Mac:

Download and install Docker Desktop from the official Docker website. The CLI tools are included.

Windows:

Download and install Docker Desktop from the official Docker website. The CLI tools are included.

Core Concepts

• Image: A read-only template with instructions for creating a Docker container. Think of it as a blueprint.
• Container: A runnable instance of a Docker image. It’s a lightweight, isolated environment.
• Dockerfile: A text file that contains instructions for building a Docker image.
• Registry: A repository for storing and distributing Docker images (e.g., Docker Hub).
• Volume: A mechanism for persisting data generated by and used by Docker containers.
• Network: A way for containers to communicate with each other and the outside world.

Commands / Usage

Managing Images

Pull an image from a registry:

docker pull ubuntu:latest

Downloads the latest tag of the ubuntu image from Docker Hub.

List local images:

docker images

Shows all Docker images stored on your local machine.

Build an image from a Dockerfile:

docker build -t my-app:1.0 .

Builds an image named my-app with tag 1.0 using the Dockerfile in the current directory.

Remove an image:

docker rmi ubuntu:latest

Removes the specified image from your local machine.

Tag an image:

docker tag my-app:1.0 your-dockerhub-username/my-app:1.0

Adds a new tag to an existing image, often used for pushing to a registry.

Push an image to a registry:

docker push your-dockerhub-username/my-app:1.0

Uploads a tagged image to a container registry (like Docker Hub).

Inspect an image:

docker inspect ubuntu:latest

Returns detailed low-level information about an image.

Managing Containers

Run a container from an image:

docker run -d -p 8080:80 --name my-web-server nginx:latest

Runs an nginx container in detached mode (-d), maps host port 8080 to container port 80 (-p), names it my-web-server, and uses the latest tag.

List running containers:

docker ps

Shows all currently running containers.

List all containers (including stopped):

docker ps -a

Shows all containers, regardless of their running state.

Stop a running container:

docker stop my-web-server

Gracefully stops a container.

Start a stopped container:

docker start my-web-server

Starts a previously stopped container.

Restart a container:

docker restart my-web-server

Restarts a container.

Remove a stopped container:

docker rm my-web-server

Removes a stopped container.

Force remove a running container:

docker rm -f my-web-server

Forcefully removes a container, even if it’s running.

View container logs:

docker logs my-web-server

Fetches the logs of a container.

Follow container logs:

docker logs -f my-web-server

Streams the logs of a container in real-time.

Execute a command in a running container:

docker exec -it my-web-server bash

Opens an interactive bash shell inside the my-web-server container.

List processes inside a container:

docker top my-web-server

Displays the running processes of a container.

Inspect a container:

docker inspect my-web-server

Returns detailed low-level information about a container.

Commit changes to an image:

docker commit my-web-server my-custom-image:v1

Creates a new image from the current state of a container’s filesystem.

Managing Volumes

List volumes:

docker volume ls

Shows all Docker volumes on your system.

Create a volume:

docker volume create my-data-volume

Creates a new named volume.

Remove a volume:

docker volume rm my-data-volume

Removes a volume.

Inspect a volume:

docker volume inspect my-data-volume

Returns detailed low-level information about a volume.

Run a container with a volume:

docker run -d -v my-data-volume:/app/data --name data-app my-app-image

Runs my-app-image and mounts my-data-volume to /app/data inside the container.

Managing Networks

List networks:

docker network ls

Shows all Docker networks on your system.

Create a network:

docker network create my-custom-network

Creates a new user-defined bridge network.

Remove a network:

docker network rm my-custom-network

Removes a network.

Inspect a network:

docker network inspect my-custom-network

Returns detailed low-level information about a network.

Connect a container to a network:

docker network connect my-custom-network my-web-server

Connects a running container to a specified network.

Disconnect a container from a network:

docker network disconnect my-custom-network my-web-server

Disconnects a running container from a specified network.

Run a container on a specific network:

docker run -d --network my-custom-network --name app-on-network my-app-image

Runs my-app-image and connects it to my-custom-network.

Docker Compose

Build, create, and start services defined in a docker-compose.yml file:

docker compose up -d

Starts all services defined in docker-compose.yml in detached mode.

Stop and remove containers, networks, and volumes defined in docker-compose.yml:

docker compose down

Stops and removes containers, networks, and volumes created by docker compose up.

List services defined in docker-compose.yml:

docker compose ps

Shows the status of services defined in docker-compose.yml.

View logs for services defined in docker-compose.yml:

docker compose logs

Displays logs from all services defined in docker-compose.yml.

Execute a command in a service defined in docker-compose.yml:

docker compose exec web bash

Opens an interactive bash shell inside the web service container.

Build or rebuild services defined in docker-compose.yml:

docker compose build

Builds or rebuilds images for services that have a build instruction.

System Management

Show Docker system-wide information:

docker info

Displays information about your Docker installation and configuration.

Show disk usage by Docker objects:

docker system df

Provides a summary of disk space used by images, containers, and volumes.

Prune unused Docker objects (containers, images, networks, volumes):

docker system prune

Removes all stopped containers, dangling images, unused networks, and build cache.

Prune all unused Docker objects (including volumes):

docker system prune -a --volumes

Removes all stopped containers, all unused images (not just dangling), all unused networks, and all unused volumes. Use with caution.

Common Patterns

Run a web server from a directory:

docker run -d -p 8000:80 -v $(pwd):/usr/share/nginx/html nginx:latest

Serves files from the current directory ($(pwd)) via Nginx on port 8000.

Run a container, get a shell, and then exit and remove it:

docker run -it --rm ubuntu:latest bash
exit

Starts an interactive Ubuntu container, provides a shell, and automatically removes the container upon exiting.

Build an image and then run a container from it:

docker build -t my-custom-app:latest . && docker run -p 8080:80 my-custom-app:latest

Builds the image and then immediately runs a container from it, mapping port 8080.

Copy files from host to container:

docker cp ./local-file.txt my-container:/container/path/

Copies local-file.txt from your host into the specified path within my-container.

Copy files from container to host:

docker cp my-container:/container/path/remote-file.txt ./local-destination/

Copies remote-file.txt from my-container to your local host.

Run a detached container and then attach to its logs:

docker run -d --name my-background-task my-app-image
docker logs -f my-background-task

Starts a task in the background and then monitors its output.

Use Docker Compose to spin up a multi-container application:

# docker-compose.yml
version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  app:
    build: .
    ports:
      - "5000:5000"

docker compose up -d

Defines and runs a web server and a custom application service.

Gotchas

• Container Naming Conflicts: If you try to run a container with a name that already exists (even for a stopped container), docker run will fail. Use docker ps -a to check for existing containers, or docker rm <container_name> to remove the old one.
• Port Conflicts: If the host port you’re trying to map (-p 8080:80) is already in use by another process on your host machine, docker run will fail.
• docker rm vs. docker system prune: docker rm only removes specific containers. docker system prune is a more aggressive cleanup tool that removes all stopped containers and dangling images. docker system prune -a removes all unused images, not just dangling ones. docker system prune -a --volumes also removes unused volumes, which can lead to data loss if not careful.
• latest Tag Behavior: The latest tag is not automatically updated. It refers to the tag that was designated as latest at the time of the docker pull or docker build. Relying solely on latest can lead to unexpected behavior if the image in the registry has changed. It’s often better to use specific version tags (e.g., ubuntu:22.04).
• File Permissions with Volumes: When mounting volumes, the user inside the container might not have the correct permissions for files and directories created on the host. This can be managed by ensuring the user ID (UID) and group ID (GID) match between the host and the container, or by adjusting permissions within the Dockerfile or on the host.
• docker exec and Container State: docker exec only works on running containers. If a container is stopped, you must start it first (docker start <container_name>) before using docker exec.
• Detached Mode (-d) and docker logs: When running in detached mode, the container runs in the background. You’ll need docker logs to view its output. If you run a container interactively (-it) and then detach, the standard output will be disconnected.
• docker stop vs. docker kill: docker stop sends a SIGTERM signal and waits for the container to shut down gracefully (default 10 seconds). docker kill sends a SIGKILL signal immediately, which forcefully terminates the container without allowing it to clean up.