Install Docker Compose

What Docker Compose is

A way to describe several containers in a single text file and start them together. A program with a database rarely consists of one container, but of two or three that need to know about each other. Starting them by hand in the right order, with the right settings, every time, is a recipe for something going wrong.

With Compose you write down the whole setup once in the file compose.yaml. After that, starting is one command, and it is the same on every computer that has the file.

That is why almost every server guide in this collection asks you to create that file. Compose is not a program you use on its own, it is the language the other guides are written in.

You probably already have it

Compose has been included with Docker for several years and is not installed separately. If you have followed Install Docker, you are done.

Check this before you install anything. Open PowerShell on Windows or Terminal on Linux Mint and type:

docker compose version

If you get a version number, you do not need to do anything else in this section. If you get an error message on Linux Mint, install the component with:

sudo apt-get install docker-compose-v2

The package docker-compose-plugin is only available in Docker's own apt repository, not in Mint's. If you have followed Install Docker and got docker.io from Mint's own repository, the package is called docker-compose-v2 instead, and that is the line you should run.

On Windows, Compose is always included in Docker Desktop, so if it is missing, Docker Desktop is not installed. Also note that Docker Desktop requires WSL2, which is Windows' built-in Linux. It is normally installed automatically, but if you are asked, answer yes.

One thing about the spelling. Older guides write docker-compose with a hyphen, which was a separate program that has now been discontinued. Newer ones write docker compose with a space. If a line you copied does not work, check that you replaced the hyphen with a space between docker and compose, not removed it. If you write the words together as dockercompose, no such command exists.

What a file looks like

Create a folder, and in it a text file named exactly compose.yaml. Write:

services:
  webb:
    image: nginx
    ports:
      - "8080:80"

Then open the terminal in that folder and run docker compose up -d. Go to http://localhost:8080, and the web server is there. Shut it down with docker compose down.

The line "8080:80" is read from right to left: the container listens on 80 internally, and you reach it from outside on 8080. That order gets mixed up all the time, and then you wonder why the page does not respond.

Three things to do first

1. Learn the indentation, because that is what trips people up. The file format is built on spaces at the start of lines, and tab characters are not allowed. Use two spaces per level and be consistent. An error message about yaml almost always means a line has the wrong number of spaces.
2. Run docker compose config before you run up. The command reads the file and prints how it was interpreted, without starting anything. If it is broken you know within a second instead of after a two-minute download.
3. Learn docker compose logs -f. If something does not start, the answer is there, always. Press Ctrl and C to exit the log, which does not shut anything down.

The most common trap

The -v flag at the end of docker compose down. Without it, the containers stop but all data remains in the volumes. With it, the volumes are deleted, and the database goes with them in the same second. No question, no confirmation.

The flag appears in plenty of guides online, because it is convenient when you are testing things and want to start over from a clean slate. On the installation where your real work lives, it should never be used. Get used to typing docker compose down and nothing more.

The other half is passwords in the file. A database password written straight into compose.yaml goes along when you put the project on GitHub, and then it is no longer a password. Put them in a file called .env next to it, refer to them in the compose file, and add .env to .gitignore. Five minutes of work that saves you an unpleasant discovery.