How to Use Docker Compose on Ubuntu 26.04 LTS – Complete Guide

Learning how to use Docker Compose on Ubuntu 26.04 LTS allows you to define and run multi-container applications using a single docker-compose.yml configuration file. The modern Docker Compose V2 utility coordinates web servers, databases, and cache layers under a unified private network with simple terminal commands. Before you begin, ensure you have Docker installed on your system. If you need to set it up, follow our companion guide on how to install Docker on Ubuntu 26.04 LTS.

What is Docker Compose?

When deploying containerized applications, running a single container is rarely sufficient. A typical web application requires a frontend web server, a backend application service, a database engine, and a cache store. Managing these services using individual, manual docker run commands is inefficient and error prone. You must manually construct networks, handle link arguments, ensure correct startup order, and track separate storage paths.

Docker Compose solves this problem by allowing you to define your entire multi-container architecture in a single configuration file named docker-compose.yml. In this file, you declare your services, configurations, dependencies, networks, and persistent data volumes. Once defined, you can initialize, start, inspect, update, and shut down the entire stack using a single command in your terminal.

Core docker-compose.yml Syntax Explained

Docker Compose files are written in YAML format. The configuration uses structured indentation to define services, volumes, and networks. Below is an annotated template demonstrating the core configuration fields you will use in daily development:

# Defines the services (containers) that compose your application
services:
  # Name of your service container (used as a local DNS hostname)
  web_server:
    # Docker image to pull from Docker Hub
    image: nginx:alpine
    # Friendly container name shown in Docker CLI lists
    container_name: web_nginx
    # Automatic restart policy (always, unless-stopped, or on-failure)
    restart: always
    # Maps container ports to host ports (host_port:container_port)
    ports:
      - "8080:80"
    # Configuration variables passed directly to the container
    environment:
      - NGINX_PORT=80
    # Mounts a host folder or a named volume inside the container
    volumes:
      - html_data:/usr/share/nginx/html
    # Connects the container to a specific virtual network
    networks:
      - app_network

# Defines persistent volumes that save data even when containers are deleted
volumes:
  html_data:

# Defines private virtual networks so containers can talk to each other securely
networks:
  app_network:
    driver: bridge

By using these service names, containers automatically resolve one another. For example, a web application container can communicate with a database container using the host address db on their shared private bridge network, without needing hardcoded IP addresses.

Real-World Working Example: WordPress and MySQL

To understand how Docker Compose coordinates containers, we will build a working multi-container deployment: a WordPress web application backed by a MySQL database. This stack uses two services, two persistent volumes, and a private bridge network.

mkdir ~/wordpress-db
cd ~/wordpress-db

nano docker-compose.yml

services:
  db:
    image: mysql:8.0
    container_name: wordpress_db
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: your_root_password
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: your_wordpress_password
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - wp_network

  wordpress:
    image: wordpress:latest
    container_name: wordpress_app
    restart: always
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: your_wordpress_password
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wp_data:/var/www/html
    networks:
      - wp_network
    depends_on:
      - db

volumes:
  db_data:
  wp_data:

networks:
  wp_network:
    driver: bridge

docker compose up -d

docker compose ps

Open your web browser and navigate to http://localhost:8080. You will see the official WordPress installation screen. The application is successfully communicating with the database running in the separate wordpress_db container on the background network.

Essential Docker Compose Commands

To manage Compose stacks efficiently, familiarize yourself with these core commands. Always run these commands from the directory containing your project’s docker-compose.yml file:

Docker Compose V2 vs. Legacy V1 Syntax

Docker Compose has transitioned from the deprecated V1 version to the modern V2 framework. Understanding the differences prevents configuration issues when reviewing legacy documentation:

docker compose up -d
docker compose down
docker compose ps

docker-compose up -d
docker-compose down
docker-compose ps

Troubleshooting Common Docker Compose Issues

sudo lsof -i :8080

# Example DB Healthcheck configuration
services:
  db:
    image: mysql:8.0
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
  wordpress:
    image: wordpress:latest
    depends_on:
      db:
        condition: service_healthy

docker compose config

Frequently Asked Questions

More Ubuntu 26.04 guides: Install Docker on Ubuntu  ·  Ubuntu Server 26.04 Download  ·  Ubuntu Server Manual  ·  Upgrade to Ubuntu 26.04 LTS