Developer Tools & Environments INTERMEDIATE Linux / macOS / Windows (WSL2) โฑ๏ธ 4 min read ๐Ÿ“… Updated: 23 Sep 2026

Setting Up Local Docker Compose Multi-Service Development Environment

This guide walks you through establishing a robust, multi-container local development environment using Docker Compose for microservices architecture.

Gurveer Singh
Gurveer Singh โœ“ Verified Specialist
Founder & Chief Architect ยท hSECURITIES Labs
โšก FAST-TRACK PROTOCOL

Direct Diagnostic & Remediation Summary

  • Prerequisite Check: Ensure Docker Engine and Docker Compose are installed. Verify with docker --version and docker compose version.
  • Project Initialization: Create the main directory and write a basic docker-compose.yml file defining all required services (e.g., database, API gateway, backend).
  • Deployment Command: Run docker compose up -d --build to build images and start all interconnected services in detached mode.
๐Ÿ› ๏ธ Tools & Prerequisites: A modern PC or Laptop running Linux (Ubuntu/Fedora), macOS, or Windows 10+/11 with WSL2 enabled. Required software: Docker Engine, Docker Compose plugin, Git for version control.
STEP 1

Prerequisites Installation and Verification

Before starting, you must ensure the core tools are installed. For Windows users, using WSL2 with a Linux distribution (like Ubuntu) is highly recommended over native PowerShell/CMD for best Docker compatibility.

Action Checklist:

  • Install Docker Desktop: Download and install Docker Desktop for your OS. Ensure it starts correctly and the daemon runs without errors.
  • Verify Installation (Linux/macOS): Open your terminal and run these commands sequentially to confirm connectivity and versioning.
docker --version
docker compose version

If any command fails, revisit the Docker Desktop installation guide for your specific operating system.

Pro Tip: For Windows users on WSL2, ensure your WSL distribution is updated and that Docker integration within WSL2 is explicitly enabled in the Docker Desktop settings.
STEP 2

Project Structure Setup & Defining Services

A microservices setup requires defining interdependencies. We will use a single docker-compose.yml file to manage all services (e.g., 'db', 'user_service', 'api_gateway').

File Creation Steps:

  1. Create your root project directory and navigate into it: mkdir my-microservices && cd my-microservices
  2. Initialize version control: git init
  3. Create the primary configuration file: touch docker-compose.yml

Populate docker-compose.yml with services. Example structure (Database and a simple API):

version: '3.8'
services:
  db:
    image: postgres:14-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: appdb
    volumes:
      - db_data:/var/lib/postgresql/data
  user_service:
    build: ./user_service  # Assumes a Dockerfile exists here
    ports:
      - "8081:80"
    depends_on:
      - db
volumes:
  db_data:
Warning: The build: ./user_service line assumes you have a subdirectory named 'user_service' containing its own Dockerfile.
STEP 3

Building and Orchestrating the Environment

This step reads the YAML file, builds the necessary images (if local code changes are present), and starts all containers in the background. This is the core deployment command.

Execution Sequence:

  1. Run the build and up command together. The --build flag forces recreation of images using local Dockerfiles, which is crucial for development.
  2. The -d flag runs all services in detached mode (in the background), allowing you to continue using your terminal for other tasks.
docker compose up -d --build

Wait several minutes. Docker will download base images, build custom ones, and start all containers listed in the docker-compose.yml file.

Verification of Running Containers:

To confirm everything started correctly:

docker compose ps

This command lists the status (e.g., 'Up') and ports for every service defined in your file.

FINAL STEP

Verification, Results & Preventative Maintenance

The environment is running. Now, we verify connectivity and establish routines for stability.

1. Connectivity Test (Service to Service):

If your user_service needs to talk to the database, it must use the service name defined in the YAML file as its hostname (e.g., connecting to db:5432 instead of localhost:5432).

docker logs user_service

Check the logs for startup errors or successful connection messages.

2. Stopping and Cleaning Up:

When development is paused, always stop and remove containers to free resources:

docker compose down

This stops and removes containers, networks, but often leaves volumes (like db_data) intact by default. To also remove persistent data volumes:

docker compose down --volumes

3. Preventative Maintenance:

  • Image Pruning: Periodically clean up unused images and containers to prevent disk space exhaustion: docker image prune -f
  • Dependency Management: Always commit your docker-compose.yml file to Git so that any new developer can replicate the exact environment with one command.
Resolution Complete: Your multi-service local development environment is fully operational using Docker Compose. To make code changes, modify the source files, then re-run docker compose up -d --build. If services fail to connect, verify hostnames and port mappings in your docker-compose.yml file against the service names.
TROUBLESHOOTING

Common Pitfalls & Advanced Troubleshooting

If standard remediation does not immediately resolve the symptoms for Setting Up Local Docker Compose Multi-Service Development Environment, review these advanced diagnostic contingencies on Linux / macOS / Windows (WSL2):

  • Peripheral & Bus Isolation: Detach non-essential USB accessories and external controllers to isolate IRQ and bus contention.
  • Diagnostic Minimal Boot: Restart Linux / macOS / Windows (WSL2) in Safe / Diagnostic Mode to eliminate third-party daemon conflicts.
  • Firmware Integrity: Check that hardware firmware and UEFI/BIOS revisions are updated to the manufacturer baseline.
COMMAND LINE / TERMINAL
docker --version
docker compose version
docker compose up -d --build
docker compose ps
docker logs user_service
docker compose down
docker image prune -f

Frequently Asked Questions

Why do I need to use <code>docker compose up -d --build</code> instead of just <code>docker-compose up</code>?

The modern syntax is <code>docker compose` (no hyphen), and adding <code>--build</code> ensures Docker rebuilds images from your local code changes, which is essential during active development.

My service cannot connect to the database even though they are in the same file.

In Docker Compose networking, containers must use the <strong>service name</strong> defined in the YAML file as the hostname (e.g., 'db'), not 'localhost' or '127.0.0.1'.

What is the difference between <code>docker compose down</code> and <code>docker compose down --volumes</code>?

<code>down</code> stops running containers and removes them. <code>down --volumes</code> performs the same action but also removes the named volumes (like persistent database storage), deleting all stored data.

Does this setup work on my corporate laptop with strict firewall rules?

If you encounter network issues, check if Docker Desktop requires specific port ranges (usually 2375/2376) to be open. You may need IT assistance to whitelist these ports.

Engineering Assistance

Need help implementing this solution?

Our cybersecurity and infrastructure engineers can audit, harden, or configure your systems directly.

Request Technical Assistance โ†’
Gurveer Singh
Gurveer Singh โœ“ Verified Author
Founder & CEO at hSECURITIES | Cybersecurity Educator | Security Researcher | Ethical Hacking Enthusiast | Technology Mentor
Meet the Founder โ†’

Gurveer Singh Saggu is the Founder and CEO of hSECURITIES, a cybersecurity and technology education platform focused on practical learning, digital security awareness, hardware diagnostics, Linux administration, and real-world cybersecurity training.

With a strong passion for technology, ethical hacking, and security education, he has spent years helping students, professionals, and organizations understand modern cyber threats and develop practical technical skills. Through hSECURITIES, he creates hands-on learning resources, technical guides, security awareness content, and community-driven initiatives that make cybersecurity more accessible.

His mission is to bridge the gap between theoretical knowledge and practical implementation by providing step-by-step learning experiences, technical troubleshooting resources, and security-focused educational platforms.

Community Discussion & Confirmations (0)

Technical questions, hardware findings, and verified fix reports.

No reader questions posted yet. Have you tried this solution or experienced an edge case? Post below.

Ask a Question or Share Solution