Composing services¶

Practical 6.5 composing-services-annex.pdf · PDF

Try to write, from memory, the command that started the database on the Images, volumes and ports page. A name, a password variable, a volume with an exact path, the image with its tag... Did you get every option right?

Now imagine a real application: the program, its database, maybe a cache. Two or three of those long commands, typed in the right order, with no typo, on every server, and still remembered in six months. Nobody can do that reliably. What you need is a file that describes what must exist, and a tool that makes it so.

One file for the whole application¶

Ships do not leave port with the crew remembering where each container goes. They carry a loading plan: a document that lists every box, where it sits and what is connected to what. Any crane operator in any port can read it.

A compose file (compose.yaml) describes an application as a set of services. Each service is one container: its image, ports, volumes and environment.

One command reads the plan and starts everything:

podman compose up -d

Docker's command is docker compose up -d, with the same file.

YAML in four rules¶

The file is written in YAML, a text format for structured data. You met it already in the Netplan file of Clients, servers and shared resources. Here is the nginx command of the intranet, translated:

podman run -d --name web -p 8080:80 -v ./site:/usr/share/nginx/html:ro docker.io/library/nginx:1.30

services:
  web:
    image: docker.io/library/nginx:1.30
    ports:
      - "8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro

1. key: value, with a space after the colon.
2. Indentation is the structure: two spaces per level, never tabs. web is inside services; image is inside web.
3. A line starting with - is an item of a list.
4. Quote the port pairs: "8080:80".

The intranet as a compose file¶

On ubu-srv, install the tool and clear the old containers:

sudo apt install -y podman-compose
podman rm -f web intranet db

Ubuntu 26.04 installs podman-compose 1.5.0. podman compose (with a space) is Podman's own subcommand: it finds the compose tool and hands it the work.

Save the YAML above as ~/intranet/compose.yaml (the site folder is already there) and check it has no tabs: cat -A compose.yaml shows a tab as ^I. Then, from ~/intranet:

podman compose up -d
podman compose ps
curl -s http://localhost:8080 | grep "<p>"
podman compose logs

• ps shows one container called intranet_web_1: project name (the folder) + service name + a number.
• up also created a network, intranet_default, for the project.
• Each log line is prefixed with the service name: [web] | ... "GET / HTTP/1.1" 200 ....

podman compose down removes the container and the network. Change the host port to 8090 in the file, up -d again, and it answers on 8090. The file is now the single source of truth: nobody needs to remember the command. Finish with down, so port 8080 is free.

A real application: Gitea and PostgreSQL¶

Gitea is a Git server with a web interface: a private GitHub inside the office, where Tramuntana's programmers keep their code. (Git itself comes in Unit 7.) Today it is simply a real application that needs a real database. The file below is the PostgreSQL example from Gitea's documentation, with named volumes and a password taken from a separate file.

The project folder is ~/app. First the secret, in a file called .env:

DB_PASSWORD=write-your-own-password-here

chmod 600 .env

Then compose.yaml:

services:
  server:
    image: docker.gitea.com/gitea:28.0.0
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${DB_PASSWORD}
    restart: always
    volumes:
      - gitea-data:/data
    ports:
      - "8080:3000"
      - "2222:22"
    depends_on:
      - db

  db:
    image: docker.io/library/postgres:18
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=gitea
    volumes:
      - db-data:/var/lib/postgresql

volumes:
  gitea-data:
  db-data:

Read it like a loading plan:

• Two services: server (Gitea) and db (PostgreSQL), so two containers.
• The database is configured with the variables you found on its Docker Hub page: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB.
• GITEA__database__HOST=db:5432: db is the service name. Inside the project's private network every service is reachable by its name, through a small DNS that Podman runs for the project.
• ports: the office can reach 8080 (the web; inside its box Gitea listens on 3000) and 2222 (Git over SSH). The database has no ports: only Gitea can talk to it.
• ${DB_PASSWORD} is replaced by the value in .env. The compose file can be shared; the .env file must not be.
• depends_on starts db before server; restart: always starts a container again if it stops.
• The last volumes: block declares the two named volumes, the warehouses for the data.

flowchart LR
    OFFICE["<b>Office PCs</b><br>browser, git"] -->|"8080 web<br>2222 Git over SSH"| SERVER
    subgraph NET ["app_default: the project's private network"]
        SERVER["<b>server</b><br>Gitea, listens on 3000"] -->|"db:5432<br>found by name"| DB["<b>db</b><br>PostgreSQL<br>no published port"]
    end
    SERVER --- V1[("gitea-data")]
    DB --- V2[("db-data")]

Deploy Tramuntana Git¶

This is the Practical 6.5 sheet. From ~/app:

podman compose up -d
podman compose ps
podman compose logs db
podman volume ls

Two containers, app_db_1 and app_server_1, both Up, with ports 0.0.0.0:2222->22/tcp, 0.0.0.0:8080->3000/tcp on the server only. The database log ends with database system is ready to accept connections, and podman volume ls lists app_db-data and app_gitea-data.

First-run setup¶

Open http://192.168.122.10:8080 in your host's browser. Gitea shows Initial Configuration:

• Database Settings are already filled in, from the environment variables. Change nothing.
• General Settings: Site Title Tramuntana Git · SSH Server Port 2222 · Gitea Website URL http://192.168.122.10:8080/. Leave HTTP Server Port at 3000: that is the port inside the container.
• Optional Settings → Administrator Account Settings: your first name, an e-mail and a password (not the database one).
• Press Install Gitea, sign in, and create a repository called intranet.

Where is the data?¶

Your repository is a row in PostgreSQL:

podman exec app_db_1 psql -U gitea -c "SELECT name FROM repository;"

One row: intranet. Now the test:

podman compose down
podman ps -a
podman volume ls
podman compose up -d

After down: no containers, no network, but both volumes are still listed. After up: the site, your user and the repository are back, with no setup page.

Survive your logout¶

The containers of a normal user stop when that user's last session ends. Tell systemd to keep them running:

sudo loginctl enable-linger $USER

Close your SSH session and reload the browser: Tramuntana Git is still there.

Key takeaways¶

• A compose file describes all the services of an application in one place; podman compose up -d starts them, down removes them. Docker uses the same file.
• YAML: key: value, lists with -, and indentation with spaces is the structure. Tabs are an error.
• Each project gets a private network; services find each other by service name (db:5432), never by localhost.
• Publish only what the office needs: the database has no ports.
• Secrets go in .env (mode 600), not in the shared compose file.
• down keeps the named volumes; down -v deletes them, and the data with them.

Quick check¶

The office server now has files, printers and an application. Next: who is allowed to do what on it, in User rights and security policies.