Docker Compose for Local Microservices | Multi-Container Orchestration

Running multiple microservices locally can be challenging, especially when you need to set up individual containers for each service and ensure they can communicate seamlessly. Docker Compose simplifies the process by allowing you to define and orchestrate multi-container applications using a single YAML file. It automates service creation, networking, and environment configuration, making it a crucial tool for developers working with microservices.

This guide demonstrates the use of Docker Compose for running local microservices, covering its use cases, service definitions, inter-container networking, and troubleshooting with practical Spring Boot examples.

Table of Contents

1. Use Case for Docker Compose
2. Defining Services in docker-compose.yml
3. Networking Between Containers
4. Running and Troubleshooting
5. Running Multiple Spring Applications
6. External Resources for Further Learning
7. Final Thoughts

---

Use Case for Docker Compose

Docker Compose solves key challenges of running microservices locally with ease and efficiency. Here’s why Compose is ideal:

Problems It Solves

1. Multi-Container Orchestration: When an application consists of multiple services (e.g., a Spring Boot app, a database, and a Redis cache), starting and managing each container manually is tedious. Compose automates this process.
2. Service Dependency Management: Compose ensures that dependent services (e.g., PostgreSQL for an application) are started in the correct order.
3. Environment Configuration: It centralizes environment variables, port configurations, and volume mappings for easier local development.
4. Networking Between Services: Compose automatically sets up an isolated network where containers can discover and communicate with each other using service names.

Benefits for a Microservices Architecture

• Simplifies local testing for APIs and databases interacting across multiple services.
• Enables consistent development environments across teams.
• Quick setup and teardown of local microservice environments.
• Integrated with Docker’s CLI, making it easy to monitor logs and troubleshoot.

---

Defining Services in docker-compose.yml

What is docker-compose.yml?

The docker-compose.yml file is a declarative configuration file that describes all services, networks, and volumes required for your application. Compose reads this file to start and manage containers.

Example of docker-compose.yml

Here’s an example for running a Spring Boot app and PostgreSQL database:

version: "3.8"

services:
  spring-app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://database/postgres
      SPRING_DATASOURCE_USERNAME: postgres
      SPRING_DATASOURCE_PASSWORD: postgres
    depends_on:
      - database

  database:
    image: postgres:15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Explanation of Key Sections

1. Version: Specifies the Compose file version. Version 3.8 is the latest, stable for most use cases.
2. Services: Defines individual containers. Here, spring-app is the application, and database is the PostgreSQL service.
3. Depends On: Ensures spring-app starts only after database is ready.
4. Environment: Passes configuration (e.g., database URLs) as environment variables to containers.
5. Volumes: Stores persistent database data, ensuring it isn’t lost when containers are restarted.

When you run this Compose file, both services are built and connected automatically.

---

Networking Between Containers

Docker Compose Networking Basics

When you use Docker Compose, all defined services are automatically assigned to a virtual network. These services can communicate with each other using their service names (e.g., spring-app can connect to database by referring to it as database, rather than using an IP).

Example Interaction

The Spring Boot application should point its database connection to the database service, as defined in the SPRING_DATASOURCE_URL:

SPRING_DATASOURCE_URL=jdbc:postgresql://database/postgres

Even if the container’s internal IP changes, this name-based communication ensures connectivity without reconfiguration.

Custom Networking

You can define custom networks for isolated communication between groups of containers:

networks:
  custom-network:
    driver: bridge

services:
  spring-app:
    networks:
      - custom-network
  database:
    networks:
      - custom-network

Now only containers within custom-network can communicate.

---

Running and Troubleshooting

Starting the Environment

To start all services defined in docker-compose.yml, run:

docker-compose up --build

Options:

• --build: Forces a rebuild of images.
• -d: Runs services in detached mode (in the background).

Stopping and Tearing Down

To stop services without deleting containers:

docker-compose stop

To stop and remove containers, networks, and volumes:

docker-compose down

Viewing Logs

Live logs for troubleshooting:

docker-compose logs -f

Logs for a specific service:

docker-compose logs spring-app

Common Issues and Solutions

1. Database Connection Issues:
   Ensure depends_on is configured properly, so the app waits for the database to initialize before starting. You can also use healthcheck to wait for database readiness. Example: healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s retries: 3
2. Port Conflicts:
   Check if the exposed ports (e.g., 8080 or 5432) are already in use. Adjust ports accordingly: ports: - "9090:8080"
3. Volume Data Persistence Issues:
   Verify volume bindings in the volumes section to retain data across container restarts.

---

Running Multiple Spring Applications

Extending the Compose File

Here’s how to include multiple Spring Boot microservices in a single docker-compose.yml file:

version: "3.8"

services:
  user-service:
    build:
      context: ./user-service
      dockerfile: Dockerfile
    ports:
      - "8081:8081"
    networks:
      - microservices-network

  order-service:
    build:
      context: ./order-service
      dockerfile: Dockerfile
    ports:
      - "8082:8082"
    networks:
      - microservices-network

networks:
  microservices-network:
    driver: bridge

Running the Microservices

1. Place separate Dockerfile and application files in user-service and order-service directories.
2. Start all services: docker-compose up --build
3. Each service will be accessible via:
   • http://localhost:8081 for user-service.
   • http://localhost:8082 for order-service.

Communicating Between Services

Use service names for inter-service communication. For example:

• order-service calls user-service at http://user-service:8081.

Add environment variables like:

USER_SERVICE_URL=http://user-service:8081

---

External Resources for Further Learning

• Docker Compose Documentation
• Networking in Compose
• Spring Boot in Containers
• Wikipedia on Microservices

---

Final Thoughts

Docker Compose is a powerful tool for orchestrating local microservices. Its ability to manage multi-container setups, networking, and environment variables simplifies development workflows, especially for Spring Boot applications. By following this guide, you are well-equipped to define services, enable seamless container communication, troubleshoot issues, and run multiple Spring Boot apps with minimal effort.

Use Docker Compose to streamline your local microservice development pipeline, and bookmark this guide for future reference when handling containerized applications!