Before you start
- Docker installed (see installing Docker on Debian or Ubuntu)
In plain words
An image is a frozen template, like a ready meal in the freezer: everything inside is already prepared. A container is that meal once heated and served: a running instance that you can stop, restart or throw away, and you can serve as many as you like from the same template. Volumes are the separate storage boxes: what you put in them survives when you throw the container away. Remember this last point: anything written inside a container without a volume disappears with it.
In the examples, sudo is left out: you need it if your account isn't in the docker group (see installing Docker).
1. Vocabulary
| Term | Definition |
|---|---|
| Image | Read-only template: minimal system, application, dependencies. Example: nginx:stable-alpine |
| Container | A running (or stopped) instance of an image |
| Tag | An image's version, after the colon: debian:13, postgres:17. Without a tag, Docker uses latest |
| Registry | The server that stores images: Docker Hub (by default), GitHub (ghcr.io), Quay, or a private registry |
| Volume | Storage space managed by Docker, which survives the container's deletion |
| Bind mount | A folder on the host mounted inside the container |
| Network | Virtual network connecting containers to each other |
| Dockerfile | The "recipe" file used to build an image |
2. Starting a container: docker run
docker run -d --name web \
--restart unless-stopped \
-p 127.0.0.1:8080:80 \
-v web-data:/usr/share/nginx/html \
nginx:stable-alpine
| Option | Role |
|---|---|
-d |
In the background (detached); without it, the container takes over the terminal |
--name web |
Gives a name; otherwise Docker makes one up |
--restart unless-stopped |
Restarts the container after a crash or a server reboot |
-p 127.0.0.1:8080:80 |
Publishes the container's port 80 on the host's port 8080, here only locally |
-v web-data:/usr/share/nginx/html |
Mounts the web-data volume in the container |
-e KEY=value |
Sets an environment variable (application configuration) |
--rm |
Deletes the container as soon as it stops (tests, one-off commands) |
-it |
Interactive mode with a terminal (for a shell) |
-p 8080:80 publishes on every interface
Without an address in front, the port is open on all the server's interfaces, bypassing ufw. Specify 127.0.0.1: (local access, behind a reverse proxy) or the local network address. See installing Docker, firewall section.
Restart policies
| Policy | Behaviour |
|---|---|
no (default) |
Never restarts automatically |
on-failure |
Only if the container stops with an error |
always |
Always, even after a manual stop, as soon as the Docker service restarts |
unless-stopped |
Always, unless you stopped it yourself: the most common choice |
Testing an image without leaving anything behind
docker run --rm -it debian:13 bash
You get a shell in a brand-new Debian 13; when you type exit, the container is deleted.
3. Managing containers
| Command | Effect |
|---|---|
docker ps |
Running containers |
docker ps -a |
All containers, including stopped ones |
docker stop web |
Stops cleanly (stop signal, then forced stop after 10 seconds) |
docker start web |
Starts a stopped container |
docker restart web |
Stops then starts |
docker rm web |
Deletes a stopped container (-f to force it if it's running) |
docker rename web site |
Renames |
docker update --restart unless-stopped web |
Changes the restart policy of an existing container |
docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
3f2a9c1e7b44 nginx:stable-alpine "/docker-entrypoint.…" 2 minutes ago Up 2 minutes 127.0.0.1:8080->80/tcp web
4. Monitoring and troubleshooting
| Command | Effect |
|---|---|
docker logs web |
The container's logs |
docker logs -f --tail 50 web |
The last 50 lines, then the rest live (Ctrl+C to quit) |
docker logs --since 1h web |
Logs from the last hour |
docker exec -it web sh |
Opens a shell inside the running container (bash if the image has it) |
docker exec web cat /etc/nginx/nginx.conf |
Runs a single command in the container |
docker inspect web |
The whole configuration as JSON: IP addresses, mounts, variables |
docker stats |
Live CPU, memory, network and disk usage |
docker top web |
Processes running in the container |
docker cp web:/etc/nginx/nginx.conf ./ |
Copies a file from the container to the host (or the other way round) |
docker port web |
Published ports |
Extracting a specific piece of information from inspect:
docker inspect -f '{{.State.Status}} {{.RestartCount}}' web
running 0
A rising RestartCount means a container is crashing in a loop: look at docker logs.
5. Images
| Command | Effect |
|---|---|
docker pull nginx:stable-alpine |
Downloads an image |
docker images |
Images on the machine |
docker rmi nginx:stable-alpine |
Deletes an image (if no container uses it) |
docker image prune |
Deletes "dangling" images (with no tag) |
docker image prune -a |
Deletes all images not used by a container |
docker image history nginx:stable-alpine |
Layers that make up the image |
Choosing your images
Prefer official images (Docker Official Image badge on Docker Hub) or those published by the software's vendor. Pin the version (postgres:17 rather than postgres:latest) so that a major update doesn't arrive unannounced. To check an image for known vulnerabilities, the open source tool Trivy takes one command: trivy image nginx:stable-alpine.
6. Volumes and mounts
| Named volume | Bind mount | |
|---|---|---|
| Syntax | -v web-data:/path |
-v /srv/web:/path (absolute path) |
| Location | Managed by Docker (/var/lib/docker/volumes/) |
A folder of your choice on the host |
| Ideal use | Databases, application data | Configuration files, content to edit from the host |
| Permissions | Managed by Docker | Watch the files' owners and permissions |
| Command | Effect |
|---|---|
docker volume ls |
Lists volumes |
docker volume inspect web-data |
Details, including the location on disk |
docker volume create web-data |
Creates a volume |
docker volume rm web-data |
Deletes a volume (and its data) |
docker volume prune |
Deletes unused anonymous volumes (-a: unused named volumes too) |
Adding :ro makes the mount read-only in the container, which is recommended for configuration: -v /srv/web/nginx.conf:/etc/nginx/nginx.conf:ro.
Backing up and restoring a volume
Back up the web-data volume to an archive in the current folder:
docker run --rm -v web-data:/data:ro -v "$PWD":/backup \
debian:13 tar czf /backup/web-data.tar.gz -C /data .
Restore into a volume (empty or new):
docker run --rm -v web-data:/data -v "$PWD":/backup \
debian:13 tar xzf /backup/web-data.tar.gz -C /data
For a database, stop the container first, or use the database's own backup tool (pg_dump, mysqldump): copying a database's files while it's writing gives an inconsistent backup.
7. Networks
| Command | Effect |
|---|---|
docker network ls |
Lists networks |
docker network create my-network |
Creates a network |
docker run --network my-network … |
Starts a container in that network |
docker network connect my-network web |
Adds an existing container to a network |
docker network inspect my-network |
Connected containers and addresses |
In a network you created (or that Compose created), containers reach each other by name: the application contacts the database at db:5432, without publishing a port on the host. The default bridge network doesn't provide this name resolution.
8. Cleaning up
| Command | What it deletes |
|---|---|
docker system df |
Nothing: shows the space used by images, containers, volumes and cache |
docker container prune |
Stopped containers |
docker image prune -a |
Unused images |
docker builder prune |
The build cache |
docker system prune |
Stopped containers, unused networks, dangling images, cache |
docker volume prune -a
By default, docker volume prune (and docker system prune --volumes) only deletes unused anonymous volumes. With -a, it also deletes named volumes not attached to any container: if you deleted a container planning to recreate it later, its data goes too. Check with docker volume ls first.
9. Building your first image
A minimal Dockerfile that serves a static web page:
FROM nginx:stable-alpine
COPY site/ /usr/share/nginx/html/
EXPOSE 80
Build, then run:
docker build -t my-site:1.0 .
docker run -d --name my-site -p 127.0.0.1:8081:80 my-site:1.0
| Instruction | Role |
|---|---|
FROM |
The starting image |
RUN |
A command run during the build (installing a package) |
COPY |
Copies project files into the image |
WORKDIR |
The working directory |
ENV |
An environment variable |
EXPOSE |
Documents the port used (publishes nothing) |
USER |
The user running the application; avoid root where possible |
CMD / ENTRYPOINT |
The command run when the container starts |
Add a .dockerignore file to exclude from the build context what has no business in the image (.git, .env files, backups).
10. Cheat sheet
| I want to… | Command |
|---|---|
| See what's running | docker ps |
| Read the logs live | docker logs -f --tail 50 name |
| Get into a container | docker exec -it name sh |
| Restart a service | docker restart name |
| Update an image | docker pull image:tag, then recreate the container |
| See resource usage | docker stats |
| Find out what's using the disk | docker system df |
| Test an image as a throwaway | docker run --rm -it image sh |
As soon as you have more than one container, or options that are long to remember, move on to Docker Compose: the configuration is written in a file and restarts with a single command.
Key points
- Image = template, container = instance, volume = data that survives the container.
docker run -d --name … --restart unless-stopped -p 127.0.0.1:port:port -v volume:/path image:tag: the basic pattern.docker ps,docker logs -f,docker exec -it … sh,docker statsto monitor and troubleshoot.- Pin image versions, prefer official images, scan them with Trivy.
- Back up your volumes, and beware of
docker volume prune -a.