Docker and Docker Compose
Every app you install by hand brings its own settings and dependencies, and they end up stepping on each other. Docker puts each app in its own box, and Docker Compose describes all the boxes in a single file.
- Course
- Tutorial 21 of 35
- Time
- 35 min to read
- Tested with
- Commands: tested on Debian 13
What you will be able to do
- Install Docker and Docker Compose from Debian's packages.
- Start, inspect and delete a container.
- Keep data in a volume.
- Describe a service in a docker-compose.yml file, start it and update it.
- Stop Docker from opening a port your firewall thinks is closed.
Before you start: Updates and packages with apt, Users, sudo and file permissions.
Contents
How do you install Docker and Docker Compose on Debian? With two packages and a few commands, it takes about half an hour. Your apps install in one line, vanish without a trace when you delete them, and stop fighting over the same files. There's also a trap waiting on the firewall side. We'll defuse it before it matters.
A container is an isolated box
A container is a closed box on your server. The app finds its own files and its own settings inside, and can't see anything else. If it breaks, it breaks its own box and nothing more. If you don't want it anymore, you throw the box away and the server stays clean.
It isn't a virtual machine, which is a full fake computer with its own system. The container borrows your server's system and only isolates the app. So it starts in a second and stays light.
Two words will come back all along, and you shouldn't mix them up:
- An image is the frozen template of an app, like a recipe. It doesn't change, and you download it.
- A container is an image that is running, like the dish cooked from the recipe. With one image, you can start as many containers as you like.
Docker is the program that downloads images and starts containers. Let's install it.
1Install Docker
Debian provides Docker as packages, pieces of software ready to install: docker.io for the program, and docker-compose for Compose. Despite its name, the second one brings the modern docker compose command, with a space. We also add curl, which asks for a web page from the terminal and will help us test.
sudo apt install -y docker.io docker-compose curlThe installation scrolls by for a minute. Then check that both commands answer.
sudo docker --version
sudo docker compose versionDocker version 26.1.5+dfsg1, build a72d7cd
Docker Compose version 2.26.1-4Install Docker from Docker's own store (optional)
Docker keeps its own software store, called a repository, next to Debian's. Its packages are newer. For a personal server, Debian's are enough and they update along with the rest of the system. If you want the latest version, first remove docker.io, then follow the "Install Docker Engine on Debian" page listed in the sources.
Docker is ready. Let's check that it can really start something.
2Start a first container
The docker run command downloads an image if it's missing, creates a container from it and starts it. The hello-world image is made for this test: it prints a message, then stops.
sudo docker run hello-worldHello from Docker!
This message shows that your installation appears to be working correctly.Above these lines, Docker showed the image being downloaded from Docker Hub, the public catalog of images. The message says everything works. Docker found the image, created the container, and the container stopped once its message was written. Now let's see a container that stays on.
3Run a real service
Let's start nginx, a web server, in a container named web. Three options of docker run matter:
-dstarts it in the background, so you keep control.--name webgives it a name you'll remember.-p 127.0.0.1:8081:80links the server's port 8081 to the container's port 80. The leading127.0.0.1keeps this port for the server itself.
That last detail protects your machine. The section on ports explains why.
sudo docker run -d --name web -p 127.0.0.1:8081:80 nginx:1.30-alpineDocker answers with a long string of letters and digits, the container's ID. The docker ps command lists the running containers. Your IDs and times will be different.
sudo docker psCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
398d49d517b9 nginx:1.30-alpine "/docker-entrypoint..." 1 second ago Up Less than a second 127.0.0.1:8081->80/tcp webNow ask the container for its page. The 200 OK in the answer means "page served".
curl -sI http://127.0.0.1:8081 | head -1HTTP/1.1 200 OKIf nothing shows up, wait two seconds for nginx to start, then run it again. Four commands will serve you every day:
sudo docker logs webshows what the container wrote, meaning its log. Add-fto follow it live, and quit with Ctrl+C.sudo docker exec web ls /usr/share/nginx/htmlruns a command inside the box, here to list the page's files. Withexec -it web sh, you get a terminal inside.sudo docker stop webstops the container without deleting it.sudo docker rm webdeletes it. You have to stop it first.
sudo docker exec web ls /usr/share/nginx/html
sudo docker stop web
sudo docker rm web50x.html
index.html
web
webDocker listed two files, then repeated the container's name on stop and on delete. The container no longer exists, and everything inside it went with it. That's handy for cleaning up, but awkward for a database. You need a place that outlives the box.
4Keep data in a volume
A volume is a folder managed by Docker, stored outside the containers, that you plug into a box. Data written there survives when the container is deleted. Let's create a volume named donnees and write a file in it, from a first container. alpine:3.20 is a tiny Linux image, used here just to run one command.
sudo docker volume create donnees
sudo docker run --rm -v donnees:/donnees alpine:3.20 sh -c 'echo bonjour > /donnees/note.txt'donneesThe option -v donnees:/donnees plugs the volume into the container's /donnees folder, and --rm deletes the container as soon as it's done. So it's already gone. Start a second, brand-new one and read the file.
sudo docker run --rm -v donnees:/donnees alpine:3.20 cat /donnees/note.txtbonjourThe file outlived the first container, and the second one finds it. That's how Nextcloud will keep your files in the next article. To erase the volume, and its data with it, you name it explicitly:
sudo docker volume rm donneesdonneesWe can start a box and keep its data. But retyping these long commands gets old fast, and sooner or later you forget an option. A file will do that job for us.
5Describe the service in a Compose file
Docker Compose reads a file named docker-compose.yml, which describes your containers, and starts them all with one command. The file is written in YAML, a format where the spaces at the start of a line show what belongs to what. Create a folder for our site, with a home page.
mkdir -p ~/mon-site/html
cd ~/mon-site
echo '<h1>Bonjour depuis mon-serveur</h1>' > html/index.htmlThen write the file. It reuses our options from earlier: the image, the port kept for the server, and the html folder plugged into nginx's. The :ro means "read-only". The restart: unless-stopped line restarts the container after a server reboot, unless you stopped it yourself.
cat > docker-compose.yml <<'EOF'
services:
web:
image: nginx:1.30-alpine
restart: unless-stopped
ports:
- "127.0.0.1:8081:80"
volumes:
- ./html:/usr/share/nginx/html:ro
EOFThe spaces at the start of a line matter, and a tab in their place makes the command fail. Start it, with -d for the background as before. Docker creates a private network for the project, then the container.
sudo docker compose up -d
sudo docker compose psNAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
mon-site-web-1 nginx:1.30-alpine "/docker-entrypoint..." web 3 seconds ago Up 2 seconds 127.0.0.1:8081->80/tcpCompose named the container after the folder: mon-site, the web service, and a number. Check that the page is ours.
curl -s http://127.0.0.1:8081<h1>Bonjour depuis mon-serveur</h1>Three commands are worth remembering, to run from the file's folder:
sudo docker compose logsshows the log of every service in the file.sudo docker compose downstops and deletes the containers and the network. Your volumes and yourhtmlfolder stay intact.sudo docker compose down -valso deletes the volumes, so the data too. Save it for a real cleanup.
That leaves updating. An image is frozen: to get a newer version, you download it again, then restart. Compose only recreates the containers whose image changed.
sudo docker compose pull
sudo docker compose up -dIf a newer version exists, Docker downloads it, then recreates the container with it. Otherwise it says everything is up to date. Here, 1.30-alpine follows the fixes of the 1.30 series. To move to a newer series, you change that number in the file.
Your site runs and updates cleanly. Now back to that 127.0.0.1 that shows up in every port. It's what saves you from a bad surprise.
The trap: Docker opens ports despite ufw
A published port is a door of the container that Docker opens on the server, with the -p option or the ports line. According to Docker's documentation, such a door stays reachable from the Internet even if your ufw firewall says otherwise. Docker writes its own rules, and connections to a container don't go through yours. We didn't reproduce this here, so take it as a safety rule.
Let's see what changes depending on how you write the port. Start two throwaway containers, one open and one kept for the server, then print their names and ports.
sudo docker run -d --name ouvert -p 8081:80 nginx:1.30-alpine
sudo docker run -d --name prive -p 127.0.0.1:8082:80 nginx:1.30-alpine
sudo docker ps --format "table {{.Names}}\t{{.Ports}}"NAMES PORTS
prive 127.0.0.1:8082->80/tcp
ouvert 0.0.0.0:8081->80/tcp, [::]:8081->80/tcpThe 0.0.0.0 sign means "every address of the server", including the Internet ([::] is its IPv6 twin). On the prive line, the 127.0.0.1 keeps the door for the server itself. Delete these two practice containers.
sudo docker rm -f ouvert priveouvert
priveHere's the rule, one spelling at a time:
| How you write it | Who can connect |
|---|---|
"8081:80" | The whole Internet, even if ufw blocks this port |
"127.0.0.1:8081:80" | The server only |
no ports line | Only the other containers in the same file |
An app kept for the server stays invisible from outside, which isn't always what you want. To show it to the world, you go through a go-between that controls what comes in: the Reverse proxy. Until then, make it a habit to write 127.0.0.1: in front of every published port.
If it fails
Five messages come back again and again, each with its cause:
permission denied while trying to connect to thefollowed by a path ending indocker.sock. You forgotsudoin front ofdocker.no configuration file provided: not found. You're not in the folder that holdsdocker-compose.yml. Acd ~/mon-sitefixes it.Bind for 127.0.0.1:8081 failed: port is already allocated. Another container, or another program, already uses this port. Read thePORTScolumn ofsudo docker ps, then change the first number in your file, for example to 8082.The container name "/web" is already in use. A container with that name already exists, even a stopped one. Delete it withsudo docker rm web, or pick another name.found character that cannot start any token, with a line number. The YAML contains a tab, or a badly made indent. Replace it with spaces.
Frequently asked questions
What is the difference between a Docker image and a container?
An image is the frozen template of an app, like a recipe. A container is an image that is running, and you can start as many as you like.
How do I keep my data when I delete a container?
Everything inside a container disappears with it. Plug in a volume, a folder managed by Docker outside the containers, and its data survives.
Does Docker bypass the ufw firewall?
According to Docker's documentation, a published port stays reachable from the Internet even if ufw blocks it. Write 127.0.0.1: in front of each published port to keep it for the server.
What's next
You know how to install Docker, start containers, keep their data, and publish a port without punching a hole in your firewall. When you're done with your tests, a sudo docker compose down in ~/mon-site frees port 8081. Now let's put all this to real work. The next article, Nextcloud, sets up your own online file space with two containers and two volumes.