Chapter 7: Composing Multi-Container Applications

Introduction

Welcome to Chapter 7! So far, you’ve mastered the art of running individual Linux containers on your Mac using Apple’s powerful container CLI. You’ve built images, run single services, and even understood the fundamental architecture that makes it all possible. That’s fantastic!

But what happens when your application isn’t just one simple service? Most modern applications are a collection of interconnected services: a web front-end, a backend API, a database, a caching layer, and perhaps more. Managing each of these as separate container run commands can quickly become a tangled mess. This is where the concept of “composing” multi-container applications comes into play.

In this chapter, we’ll dive deep into defining, running, and managing multi-service applications using Apple’s container tools. You’ll learn how to declare all your services, their dependencies, networks, and volumes in a single, easy-to-read configuration file. By the end, you’ll be able to orchestrate complex applications on your Mac with confidence and ease. Get ready to level up your container game!

Prerequisites

Before we begin, please ensure you have:

A working installation of Apple’s container CLI (we’ll assume version 1.2.0 for this guide, released on or before 2026-02-25).
A solid understanding of basic container commands (like container build, container run, container images).
Familiarity with Dockerfile syntax for building container images.
Basic knowledge of networking concepts.

Core Concepts: Orchestrating Your Services

When you have multiple containers that need to work together, you need a way to define their relationships, how they communicate, and how their data is managed. This is precisely what a “compose” tool provides.

Why Compose? The Need for Harmony

Imagine you’re building a blogging platform. You’d likely have:

A web server (e.g., Nginx or Apache) to serve static files.
A backend application (e.g., Python Flask, Node.js Express) to handle logic and API requests.
A database (e.g., PostgreSQL, MySQL) to store blog posts, users, etc.

Each of these components would live in its own container. How do you:

Start them all in the correct order? (Database before backend, backend before web server)
Allow them to talk to each other securely?
Ensure the database’s data persists even if the container is removed?
Manage configurations like port mappings and environment variables for each?

Manually running container run commands for each service becomes tedious and error-prone. This is where a declarative tool, like the compose functionality within Apple’s container CLI, shines. It lets you define your entire application stack in a single file, and then manage it with simple, high-level commands.

Introducing Apple Container Compose

Apple’s container CLI, like other container runtimes, provides a way to define and run multi-container applications using a compose.yaml (or docker-compose.yaml) file. This file uses the YAML format to describe your services, networks, and volumes. When you run a container compose command, the CLI reads this file and orchestrates your application stack automatically.

Think of it like a blueprint for your entire application. Instead of telling the construction crew (your container CLI) to build each room individually, you hand them a complete architectural drawing and say, “Build this house!”

flowchart TD User[User's Browser] --> WebApp[Web Application Service] subgraph Compose_Project["Apple Container Compose Project"] WebApp --> APIService[API Service] APIService --> Database[Database Service] end

Figure 7.1: A multi-container application orchestrated by Apple Container Compose.

The `compose.yaml` File: Your Application Blueprint

The compose.yaml file is the heart of your multi-container application definition. It’s typically placed at the root of your project directory. Let’s break down its key top-level sections:

version: Specifies the Compose file format version. This helps the container CLI understand the syntax. For 2026-02-25, 3.8 or 3.9 are common and widely supported versions.
services: This is where you define each individual container that makes up your application. Each service is essentially a single container instance.
networks: (Optional but recommended) Defines custom networks for your services. This allows containers to communicate with each other using their service names as hostnames, providing better isolation and organization.
volumes: (Optional but crucial) Defines named volumes for persistent data storage. This ensures that important data (like your database contents) isn’t lost when containers are stopped or removed.

Diving into `services`

Each service under the services section will have its own configuration. Here are some common directives you’ll use:

image: Specifies the Docker image to use for this service (e.g., postgres:16-alpine, nginx:latest). If you don’t specify build, it will pull this image from a registry.
build: If you want to build an image from a Dockerfile for this service, you specify the path to the build context (usually . for the current directory) and optionally the Dockerfile name (dockerfile: ./path/to/Dockerfile).
ports: Maps ports from the host machine to the container. For example, "8000:80" maps port 8000 on your Mac to port 80 inside the container.
environment: Sets environment variables inside the container. This is crucial for passing configuration, like database credentials or API keys.
depends_on: Declares dependencies between services. For example, your web app depends_on the database. This ensures the database starts before the web app. Important: depends_on only ensures startup order, not that the dependent service is ready to accept connections. You often need application-level retry logic for true readiness.
networks: Assigns the service to one or more custom networks defined in the networks section.
volumes: Mounts host paths or named volumes into the container for data persistence or sharing.

Networking Between Containers

When you use container compose, it automatically sets up a default network for all services defined in your compose.yaml file. This allows services to communicate with each other using their service names as hostnames.

For instance, if you have a database service and a webapp service, your webapp can connect to the database using database as the hostname and the database’s internal port. No need to worry about IP addresses!

Data Persistence with Volumes

Containers are designed to be ephemeral. If you stop and remove a container, any data written inside it is lost. For databases, user uploads, or any stateful information, this is unacceptable.

compose.yaml allows you to define volumes. These are special storage locations managed by the container CLI that persist independently of any specific container. You can then “mount” these volumes into your services.

Named Volumes: These are the preferred way to store persistent data. They are managed by the container CLI and referenced by name.

# Example snippet for a named volume
volumes:
  db_data:

services:
  database:
    image: postgres:16-alpine
    volumes:
      - db_data:/var/lib/postgresql/data # Mounts the named volume into the container

Step-by-Step Implementation: Building a Flask Web App with PostgreSQL

Let’s put these concepts into practice by building a simple Python Flask web application that stores data in a PostgreSQL database.

Step 1: Project Setup

First, create a new directory for our project. Open your terminal:

mkdir flask-postgres-app
cd flask-postgres-app

This command creates a new folder named flask-postgres-app and then changes your current directory into it. All our project files will live here.

Step 2: Create the Flask Web Application

We’ll create a simple Flask application that connects to PostgreSQL, creates a table, and allows us to add and view messages.

Create a file named app.py in your flask-postgres-app directory:

# flask-postgres-app/app.py
import os
from flask import Flask, render_template_string, request, redirect, url_for
import psycopg2

app = Flask(__name__)

# Retrieve database connection details from environment variables
DB_HOST = os.environ.get("DB_HOST", "localhost")
DB_NAME = os.environ.get("DB_NAME", "mydatabase")
DB_USER = os.environ.get("DB_USER", "user")
DB_PASS = os.environ.get("DB_PASS", "password")

def get_db_connection():
    """Establishes a connection to the PostgreSQL database."""
    try:
        conn = psycopg2.connect(
            host=DB_HOST,
            database=DB_NAME,
            user=DB_USER,
            password=DB_PASS
        )
        return conn
    except psycopg2.Error as e:
        print(f"Error connecting to database: {e}")
        return None

def init_db():
    """Initializes the database by creating the messages table if it doesn't exist."""
    conn = get_db_connection()
    if conn:
        cur = conn.cursor()
        cur.execute('''
            CREATE TABLE IF NOT EXISTS messages (
                id SERIAL PRIMARY KEY,
                content TEXT NOT NULL
            );
        ''')
        conn.commit()
        cur.close()
        conn.close()
        print("Database initialized.")
    else:
        print("Could not initialize database: No connection.")

# HTML template for our simple web page
HTML_TEMPLATE = """
<!DOCTYPE html>
<html>
<head>
    <title>Flask-Postgres App</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; }
        form { margin-bottom: 20px; }
        ul { list-style-type: none; padding: 0; }
        li { background-color: #f0f0f0; margin-bottom: 5px; padding: 10px; border-radius: 5px; }
    </style>
</head>
<body>
    <h1>Messages</h1>
    <form method="POST" action="/">
        <input type="text" name="message" placeholder="Enter your message" required>
        <button type="submit">Add Message</button>
    </form>
    <h2>All Messages:</h2>
    <ul>
        {% for message in messages %}
            <li>{{ message[1] }}</li>
        {% endfor %}
    </ul>
</body>
</html>
"""

@app.route("/", methods=["GET", "POST"])
def index():
    """Handles displaying and adding messages."""
    conn = get_db_connection()
    if conn is None:
        return "<h1>Database connection error! Check logs.</h1>", 500

    cur = conn.cursor()

    if request.method == "POST":
        message_content = request.form["message"]
        cur.execute("INSERT INTO messages (content) VALUES (%s)", (message_content,))
        conn.commit()
        cur.close()
        conn.close()
        return redirect(url_for("index")) # Redirect to prevent re-submission on refresh

    cur.execute("SELECT * FROM messages ORDER BY id DESC")
    messages = cur.fetchall()
    cur.close()
    conn.close()
    return render_template_string(HTML_TEMPLATE, messages=messages)

if __name__ == "__main__":
    init_db() # Initialize DB when app starts
    app.run(host="0.0.0.0", port=5000)

Explanation:

This is a basic Flask application.
It uses psycopg2 to connect to a PostgreSQL database.
Database connection parameters (DB_HOST, DB_NAME, DB_USER, DB_PASS) are read from environment variables. This is a crucial best practice for containerized applications, as it allows configuration without modifying code.
get_db_connection() attempts to connect to the database.
init_db() creates a messages table if it doesn’t already exist.
The / route handles both displaying existing messages (GET request) and adding new ones (POST request).
app.run(host="0.0.0.0", port=5000) makes the Flask app accessible from outside the container on port 5000.

Next, create a requirements.txt file in the same directory. This lists the Python packages our Flask app needs:

# flask-postgres-app/requirements.txt
Flask==3.0.3
psycopg2-binary==2.9.9

Explanation:

Flask is our web framework.
psycopg2-binary is the PostgreSQL adapter for Python. We specify exact versions for reproducibility.

Step 3: Create a Dockerfile for the Flask App

Now, let’s create a Dockerfile to build an image for our Flask application. This file should also be in the flask-postgres-app directory.

# flask-postgres-app/Dockerfile
# Use a lightweight Python base image
FROM python:3.11-slim-bookworm

# Set the working directory inside the container
WORKDIR /app

# Copy the requirements file and install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy the Flask application code
COPY app.py .

# Expose the port our Flask app runs on
EXPOSE 5000

# Set environment variables for the Flask app (default values)
ENV FLASK_APP=app.py
ENV FLASK_RUN_HOST=0.0.0.0
ENV FLASK_RUN_PORT=5000

# Command to run the Flask application
CMD ["python", "app.py"]

Explanation:

FROM python:3.11-slim-bookworm: We start with a slim Python 3.11 image based on Debian Bookworm, which is efficient.
WORKDIR /app: Sets the current directory inside the container to /app.
COPY requirements.txt .: Copies our requirements.txt file into the container.
RUN pip install --no-cache-dir -r requirements.txt: Installs the Python dependencies. --no-cache-dir saves space.
COPY app.py .: Copies our Flask application code into the container.
EXPOSE 5000: Informs the container CLI that the container listens on port 5000.
ENV FLASK_APP=app.py ...: Sets default environment variables. These can be overridden by compose.yaml.
CMD ["python", "app.py"]: This is the command that gets executed when the container starts.

At this point, your flask-postgres-app directory should look like this:

flask-postgres-app/
├── app.py
├── Dockerfile
└── requirements.txt

Step 4: Define the Multi-Container Application with `compose.yaml`

Now for the main event! We’ll create our compose.yaml file to define both the Flask web application and the PostgreSQL database service. This file should also be in the flask-postgres-app directory.

# flask-postgres-app/compose.yaml
version: '3.8' # Specify the Compose file format version

services:
  webapp: # Define our Flask web application service
    build: . # Build the image from the current directory (where Dockerfile is)
    ports:
      - "5000:5000" # Map host port 5000 to container port 5000
    environment: # Environment variables for the webapp container
      DB_HOST: database # Use the service name 'database' as the hostname
      DB_NAME: mydatabase
      DB_USER: user
      DB_PASS: password
    depends_on: # Ensure the database service starts before the webapp
      - database
    networks: # Connect to our custom network
      - app_network

  database: # Define our PostgreSQL database service
    image: postgres:16-alpine # Use the official PostgreSQL 16 Alpine image
    environment: # Environment variables for the database container
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes: # Mount a named volume for persistent database data
      - db_data:/var/lib/postgresql/data # This is where Postgres stores its data
    networks: # Connect to our custom network
      - app_network

networks: # Define a custom network for our services
  app_network:
    driver: bridge # The default network driver

volumes: # Define a named volume for persistent database data
  db_data: # The name of our volume

Explanation (breaking down the compose.yaml):

version: '3.8': Specifies the Compose file format. Using 3.8 provides robust features for our needs.
services:: This is the top-level key for defining all individual services.
- webapp::
  - build: .: Tells container compose to look for a Dockerfile in the current directory (.) and build an image for this service.
  - ports: - "5000:5000": Maps port 5000 on your Mac (host) to port 5000 inside the webapp container. This is how you’ll access the Flask app from your browser.
  - environment:: Sets environment variables within the webapp container. Notice DB_HOST: database. Because both webapp and database are on the same app_network, container compose automatically provides DNS resolution, so database is the hostname for the PostgreSQL service.
  - depends_on: - database: Ensures that the database service is started before the webapp service. Remember, this is a startup order, not a “ready” check.
  - networks: - app_network: Connects the webapp service to our custom app_network.
- database::
  - image: postgres:16-alpine: Pulls the official PostgreSQL version 16 image (using the lightweight Alpine variant) from container’s default registry (which typically defaults to Docker Hub).
  - environment:: These POSTGRES_ prefixed variables are standard for configuring the official PostgreSQL image. They set the database name, user, and password.
  - volumes: - db_data:/var/lib/postgresql/data: This is critical for data persistence. It mounts the named volume db_data (which we define later) into the container at /var/lib/postgresql/data. This is the default location where PostgreSQL stores its data.
  - networks: - app_network: Connects the database service to our custom app_network.
networks::
- app_network:: Defines a custom network named app_network.
- driver: bridge: Specifies the network driver. bridge is the default and most common for single-host setups.
volumes::
- db_data:: Defines a named volume called db_data. container compose will create and manage this volume.

Step 5: Running Your Multi-Container Application

With all files in place, you’re ready to bring your application to life! Make sure you are in the flask-postgres-app directory in your terminal.

container compose up -d

Explanation:

container compose up: Reads your compose.yaml file, builds the webapp image (if not already built), pulls the postgres image, creates the network and volume, and starts both services.
-d: Runs the containers in “detached” mode, meaning they run in the background, freeing up your terminal.

You’ll see output indicating image pulling, building, and container creation. It might take a moment the first time as images are downloaded.

To check the status of your running services:

container compose ps

This command will show you the services defined in your compose.yaml, their status, and their port mappings. You should see webapp and database both in an Up state.

Step 6: Interacting with the Application

Open your web browser and navigate to http://localhost:5000.

You should see your simple Flask application. Try typing a message into the input field and clicking “Add Message”. The message will be stored in the PostgreSQL database running in its own container, and then displayed on the page.

To prove data persistence, try this:

Add a few messages in your browser.
Stop the application:
```
container compose stop
```
(This stops the containers but doesn’t remove them or their data.)
Start it again:
```
container compose start
```
Refresh your browser at http://localhost:5000. Your messages should still be there! The db_data volume saved your database content.

If you wanted to remove the containers and their associated data (including the db_data volume), you would use:

container compose down -v

Caution: down -v will delete your db_data volume and all its contents! Only use this if you want to completely reset your application’s data.

Mini-Challenge: Add a Redis Cache

You’ve successfully built a two-service application! Now, let’s enhance it.

Challenge: Integrate a Redis caching service into your flask-postgres-app.

Add a new redis service to your compose.yaml file. Use the redis:7-alpine image.
Modify your webapp service to depends_on the new redis service as well.
(Optional, for extra credit) Modify your Flask app.py to actually use Redis for a simple cache (e.g., store a counter or frequently accessed data). You’d need to add redis to requirements.txt and install it. For this challenge, just getting the service up and connected to the network is enough.

Hint:

You’ll need to add a new service block under services in compose.yaml.
Redis typically runs on port 6379. You don’t usually need to expose this port to the host (ports mapping) unless you want to access Redis directly from your Mac. Just connecting it to app_network is sufficient for the webapp to reach it.
The redis:7-alpine image is very straightforward; it usually doesn’t need many environment variables for basic use.

What to Observe/Learn:

How easy it is to add new services to an existing compose.yaml.
How container compose handles bringing up multiple services and their dependencies.
The power of internal networking using service names.

Once you’re done, run container compose up -d again and verify all three services are running with container compose ps.

Common Pitfalls & Troubleshooting

Even with compose.yaml, things can sometimes go sideways. Here are a few common issues and how to approach them:

“Service ‘X’ exited with code Y” / Container Fails to Start:
- Cause: This usually means there’s an error in your container’s entrypoint command, application code, or environment variables.
- Fix:
  - Run container compose logs <service_name> (e.g., container compose logs webapp) to see the application’s output and error messages.
  - Run container compose up (without -d) to see logs directly in your terminal, which can be easier for debugging startup issues.
  - Try to container run the problematic service’s image directly with interactive mode (-it) and a shell (/bin/bash) to inspect its filesystem and manually try commands.
  - Double-check environment variables in compose.yaml match what your application expects.
“Could not connect to database” / Networking Issues:
- Cause: The services can’t communicate with each other. This is often due to incorrect hostnames, port numbers, or network misconfigurations.
- Fix:
  - Hostname: Always use the service name (e.g., database, redis) as the hostname when connecting from one service to another within the same compose network. Do not use localhost or 127.0.0.1 unless connecting to a service within the same container.
  - Ports: Ensure your application is configured to listen on the correct internal port and that any ports mappings are correct if you’re trying to access from the host.
  - networks: Verify all services that need to communicate are part of the same custom network (like app_network in our example).
  - depends_on: While it ensures startup order, add retry logic in your application. A database might start, but take a few more seconds to be ready for connections.
Volume Permission Errors:
- Cause: The user inside your container doesn’t have the necessary permissions to write to a mounted volume, especially if you’re mounting a host path.
- Fix:
  - For named volumes (like db_data), the container CLI usually handles permissions well.
  - If mounting host paths (./data:/app/data), ensure the user inside the container has read/write access to that path on your Mac. You might need to adjust permissions on the host directory (chmod) or configure the user inside your Dockerfile.
Port Conflicts:
- Cause: You’re trying to map a container port to a host port that is already in use by another application on your Mac.
- Fix: Change the host port in your ports mapping (e.g., "5001:5000" instead of "5000:5000"). You can use lsof -i :<port_number> in your terminal to check if a port is in use.

Remember, the container compose logs command is your best friend for debugging multi-container applications!

Summary

Congratulations! You’ve successfully navigated the complexities of multi-container applications using Apple’s container CLI and its compose functionality.

Here are the key takeaways from this chapter:

Compose for Orchestration: compose.yaml files provide a declarative way to define and manage multi-service applications, simplifying their setup and teardown.
compose.yaml Structure: You learned about the version, services, networks, and volumes sections, which are the building blocks of your application blueprint.
Service Definition: Each service specifies its image, build context, port mappings, environment variables, and dependencies.
Internal Networking: Services within the same compose project can communicate seamlessly using their service names as hostnames.
Data Persistence: Named volumes are essential for ensuring that critical application data (like database contents) persists across container lifecycles.
Core Commands: You used container compose up -d to start your application in the background, container compose ps to check its status, container compose stop to halt it, and container compose down -v to remove everything (including data).
Troubleshooting: You’re now equipped to diagnose common issues like container startup failures, networking problems, and port conflicts.

You’re now capable of deploying and managing sophisticated, multi-tiered applications directly on your Mac using native Apple tools. This is a huge leap forward in your developer workflow!

What’s Next?

In the next chapter, we’ll explore more advanced topics, including integrating Apple’s container tools into your development workflow, advanced networking configurations, and perhaps even a peek into CI/CD considerations. Keep exploring, and happy containerizing!

References

Apple Container GitHub Repository: https://github.com/apple/container
Apple Container how-to.md Documentation: https://github.com/apple/container/blob/main/docs/how-to.md
Apple Container tutorial.md Documentation: https://github.com/apple/container/blob/main/docs/tutorial.md
Mermaid.js Official Documentation: https://mermaid.js.org/syntax/flowchart.html
Compose file format reference (relevant for compose.yaml structure): https://docs.docker.com/compose/compose-file/

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.

Chapter 7: Composing Multi-Container Applications

Table of Contents

Introduction

Prerequisites

Core Concepts: Orchestrating Your Services

Why Compose? The Need for Harmony

Introducing Apple Container Compose

The compose.yaml File: Your Application Blueprint

Diving into services

Networking Between Containers

Data Persistence with Volumes

Step-by-Step Implementation: Building a Flask Web App with PostgreSQL

Step 1: Project Setup

Step 2: Create the Flask Web Application

Step 3: Create a Dockerfile for the Flask App

Step 4: Define the Multi-Container Application with compose.yaml

Step 5: Running Your Multi-Container Application

Step 6: Interacting with the Application

Mini-Challenge: Add a Redis Cache

Common Pitfalls & Troubleshooting

Summary

What’s Next?

References

The `compose.yaml` File: Your Application Blueprint

Diving into `services`

Step 4: Define the Multi-Container Application with `compose.yaml`