How to Build and Deploy a Multi-container Application with Docker Compose

ByAkensai

Learning how to build and deploy a multi-container application with Docker Compose is essential for modern web development. This powerful orchestration tool simplifies the management of complex applications that require multiple services working together. Instead of manually configuring each container, Docker Compose allows you to define your entire application stack in a single YAML file.

Modern web applications rarely run in isolation. They typically require databases, web servers, caching layers, and various microservices. Managing these components individually becomes complex and error-prone. Docker Compose solves this challenge by providing a declarative way to define and run multi-container applications.

In this tutorial, you’ll learn to create a complete web application stack using WordPress, MySQL, and Nginx. This practical example demonstrates real-world containerization patterns. You’ll understand how containers communicate, share data, and scale together. By the end, you’ll have a production-ready deployment strategy that you can adapt for any multi-container project.

Prerequisites and Requirements for Building Multi-container Applications with Docker Compose

Before you begin this tutorial, ensure you have the necessary tools and knowledge. You’ll need a Linux server or local development environment with Docker installed. Ubuntu 20.04 or later provides excellent compatibility with Docker and Docker Compose.

First, verify your Docker installation by running the version command:

docker --version
docker-compose --version

You should see version information for both tools. If Docker isn’t installed, follow the official Docker installation guide for your operating system.

Your system needs at least 2GB of RAM and 10GB of free disk space. Multi-container applications consume more resources than single containers. Basic knowledge of YAML syntax is helpful since Docker Compose uses YAML configuration files.

You should understand fundamental Docker concepts like images, containers, and volumes. Familiarity with web server configuration and database management will help you understand the application architecture we’re building.

This tutorial takes approximately 30-45 minutes to complete. You’ll create configuration files, build containers, and test the deployment. Keep terminal access open throughout the process.

Step-by-Step Guide to Build and Deploy Multi-container Applications with Docker Compose

Related article: How to Use Tcp/udp Streams in Nginx

Let’s build a complete WordPress application stack with MySQL database and Nginx reverse proxy. This example demonstrates key concepts you’ll use in production environments.

Step 1: Create the Project Directory Structure

Start by creating a organized directory structure for your project:

mkdir wordpress-stack
cd wordpress-stack
mkdir nginx mysql-data wordpress-data

This structure separates configuration files and persistent data. The mysql-data and wordpress-data directories will store persistent information outside containers.

Step 2: Create the Docker Compose Configuration

Create the main docker-compose.yml file that defines your entire application:

nano docker-compose.yml

Add the following configuration:

version: '3.8'

services:
  mysql:
    image: mysql:8.0
    container_name: wordpress_mysql
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: secure_password
      MYSQL_ROOT_PASSWORD: root_password
    volumes:
      - ./mysql-data:/var/lib/mysql
    networks:
      - wordpress-network

  wordpress:
    image: wordpress:latest
    container_name: wordpress_app
    restart: unless-stopped
    depends_on:
      - mysql
    environment:
      WORDPRESS_DB_HOST: mysql:3306
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: secure_password
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - ./wordpress-data:/var/www/html
    networks:
      - wordpress-network

  nginx:
    image: nginx:alpine
    container_name: wordpress_nginx
    restart: unless-stopped
    depends_on:
      - wordpress
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./wordpress-data:/var/www/html
    networks:
      - wordpress-network

networks:
  wordpress-network:
    driver: bridge

volumes:
  mysql-data:
  wordpress-data:

Step 3: Configure Nginx Reverse Proxy

Create the Nginx configuration file to handle web requests:

nano nginx/nginx.conf

Add this configuration:

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    upstream wordpress {
        server wordpress:80;
    }

    server {
        listen 80;
        server_name localhost;

        location / {
            proxy_pass http://wordpress;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        location ~ /.ht {
            deny all;
        }
    }
}

Step 4: Deploy the Multi-container Application

Now launch your complete application stack with a single command:

docker-compose up -d

The -d flag runs containers in detached mode. Docker Compose will download required images, create containers, and establish networking between services.

Step 5: Verify Container Status

Check that all containers are running properly:

docker-compose ps

You should see three containers in “Up” status. If any container shows an error, check the logs:

docker-compose logs [service-name]

Step 6: Test the Application

Open your web browser and navigate to http://localhost. You should see the WordPress installation screen. This confirms that all services are communicating correctly.

Complete the WordPress setup by following the installation wizard. The database connection will work automatically because containers can communicate using service names.

Step 7: Manage the Application Stack

Use these commands to control your multi-container application:

# Stop all services
docker-compose stop

# Start stopped services
docker-compose start

# Restart all services
docker-compose restart

# View real-time logs
docker-compose logs -f

# Remove everything (containers, networks, volumes)
docker-compose down -v

Troubleshooting Common Docker Compose Multi-container Issues

When working with multi-container applications, you might encounter specific challenges. Here are solutions to common problems that occur during deployment.

Database Connection Failures

If WordPress can’t connect to MySQL, check the database container logs first:

docker-compose logs mysql

Ensure the MySQL container is fully initialized before WordPress starts. Add a health check to your docker-compose.yml:

mysql:
  image: mysql:8.0
  healthcheck:
    test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
    timeout: 20s
    retries: 10

Port Conflicts

If port 80 is already in use, modify the nginx port mapping:

ports:
  - "8080:80"

Then access your application at http://localhost:8080.

Permission Issues with Volumes

Set proper ownership for mounted directories:

sudo chown -R www-data:www-data wordpress-data
sudo chown -R 999:999 mysql-data

Container Communication Problems

Verify that containers are on the same network:

docker network ls
docker network inspect wordpress-stack_wordpress-network

All services should appear in the network’s container list.

For detailed debugging, access container shells to test connectivity:

docker exec -it wordpress_app bash
ping mysql

The Docker Compose troubleshooting documentation provides additional debugging strategies for complex scenarios.

Resource Limitations

Monitor container resource usage if performance is poor:

docker stats

Increase Docker’s memory allocation if containers are being killed due to resource constraints.

Scaling and Production Considerations

Once you’ve mastered the basics, consider production deployment strategies. Docker Compose supports scaling services horizontally by running multiple instances.

Scale your WordPress application to handle more traffic:

docker-compose up -d --scale wordpress=3

This creates three WordPress containers behind the Nginx load balancer. Update your Nginx configuration to distribute requests across multiple backends.

For production environments, implement proper security measures. Use Docker secrets for sensitive data instead of environment variables. Configure SSL certificates and enable HTTPS in your Nginx configuration.

Consider using Docker Swarm or Kubernetes for production orchestration. These platforms provide advanced features like automatic failover, rolling updates, and cluster management that Docker Compose doesn’t offer.

Monitor your applications using tools like Prometheus and Grafana. Container logs should be centralized using solutions like ELK stack or Fluentd. The Docker Compose production guide covers these topics in detail.

Implement backup strategies for persistent data volumes. Regular database backups and file system snapshots ensure data recovery capabilities.

Understanding how to build and deploy a multi-container application with Docker Compose opens doors to modern application architecture. You’ve created a complete web application stack that demonstrates container orchestration principles. This foundation supports more complex deployments involving microservices, API gateways, and distributed databases. The skills you’ve learned apply to any multi-container project, from development environments to production deployments. Continue exploring Docker Compose features like health checks, resource limits, and service discovery to build even more sophisticated applications.

Similar Posts