Anime-Sanctuary

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
  1. A container is an isolated box
  2. Install Docker
  3. Start a first container
  4. Run a real service
  5. Keep data in a volume
  6. Describe the service in a Compose file
  7. The trap: Docker opens ports despite ufw
  8. If it fails
  9. Frequently asked questions
  10. What's next
  11. Sources

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.

On the server
sudo apt install -y docker.io docker-compose curl

The installation scrolls by for a minute. Then check that both commands answer.

On the server
sudo docker --version
sudo docker compose version
Expected output
Docker version 26.1.5+dfsg1, build a72d7cd
Docker Compose version 2.26.1-4
Install 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.

On the server
sudo docker run hello-world
Expected output
Hello 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:

  • -d starts it in the background, so you keep control.
  • --name web gives it a name you'll remember.
  • -p 127.0.0.1:8081:80 links the server's port 8081 to the container's port 80. The leading 127.0.0.1 keeps this port for the server itself.

That last detail protects your machine. The section on ports explains why.

On the server
sudo docker run -d --name web -p 127.0.0.1:8081:80 nginx:1.30-alpine

Docker 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.

On the server
sudo docker ps
Expected output
CONTAINER 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   web

Now ask the container for its page. The 200 OK in the answer means "page served".

On the server
curl -sI http://127.0.0.1:8081 | head -1
Expected output
HTTP/1.1 200 OK

If nothing shows up, wait two seconds for nginx to start, then run it again. Four commands will serve you every day:

  • sudo docker logs web shows what the container wrote, meaning its log. Add -f to follow it live, and quit with Ctrl+C.
  • sudo docker exec web ls /usr/share/nginx/html runs a command inside the box, here to list the page's files. With exec -it web sh, you get a terminal inside.
  • sudo docker stop web stops the container without deleting it.
  • sudo docker rm web deletes it. You have to stop it first.
On the server
sudo docker exec web ls /usr/share/nginx/html
sudo docker stop web
sudo docker rm web
Expected output
50x.html
index.html
web
web

Docker 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.

On the server
sudo docker volume create donnees
sudo docker run --rm -v donnees:/donnees alpine:3.20 sh -c 'echo bonjour > /donnees/note.txt'
Expected output
donnees

The 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.

On the server
sudo docker run --rm -v donnees:/donnees alpine:3.20 cat /donnees/note.txt
Expected output
bonjour

The 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:

On the server
sudo docker volume rm donnees
Expected output
donnees

We 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.

On the server
mkdir -p ~/mon-site/html
cd ~/mon-site
echo '<h1>Bonjour depuis mon-serveur</h1>' > html/index.html

Then 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.

On the server
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
EOF

The 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.

On the server
sudo docker compose up -d
sudo docker compose ps
Expected output
NAME             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/tcp

Compose named the container after the folder: mon-site, the web service, and a number. Check that the page is ours.

On the server
curl -s http://127.0.0.1:8081
Expected output
<h1>Bonjour depuis mon-serveur</h1>

Three commands are worth remembering, to run from the file's folder:

  • sudo docker compose logs shows the log of every service in the file.
  • sudo docker compose down stops and deletes the containers and the network. Your volumes and your html folder stay intact.
  • sudo docker compose down -v also 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.

On the server
sudo docker compose pull
sudo docker compose up -d

If 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.

On the server
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}}"
Expected output
NAMES     PORTS
prive     127.0.0.1:8082->80/tcp
ouvert    0.0.0.0:8081->80/tcp, [::]:8081->80/tcp

The 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.

On the server
sudo docker rm -f ouvert prive
Expected output
ouvert
prive

Here's the rule, one spelling at a time:

How you write itWho can connect
"8081:80"The whole Internet, even if ufw blocks this port
"127.0.0.1:8081:80"The server only
no ports lineOnly 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 the followed by a path ending in docker.sock. You forgot sudo in front of docker.
  • no configuration file provided: not found. You're not in the folder that holds docker-compose.yml. A cd ~/mon-site fixes it.
  • Bind for 127.0.0.1:8081 failed: port is already allocated. Another container, or another program, already uses this port. Read the PORTS column of sudo 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 with sudo 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.