DEV Community

Cover image for 10 Best Practices for Writing Maintainable Docker Compose Files
Wallace Freitas
Wallace Freitas

Posted on

10 Best Practices for Writing Maintainable Docker Compose Files

For developers working with multi-container applications, Docker Compose is a necessary tool. Web servers, databases, caches, and other related services can be defined and managed more easily with its help. However, your docker-compose.yml files can also become more sophisticated as your applications evolve. Creating maintainable Compose files guarantees that your project will continue to be simple to oversee, debug, and grow over time. Ten best practices that can assist you in producing dependable, scalable, and clean Docker Compose files will be discussed in this post.

1. Use Versioning Properly

👉🏻 Specify the version field at the top of your Compose file to ensure compatibility.

👉🏻 Use the latest stable version (e.g., version: "3.9") unless constrained by project requirements.

version: "3.9"
services:
  web:
    image: node:20
Enter fullscreen mode Exit fullscreen mode

2. Keep Services Modular and Purpose-Driven

👉🏻 Each service should do one thing well (e.g., one for Node.js API, another for PostgreSQL).

👉🏻 Avoid combining unrelated functionality into a single service to make debugging easier.

3. Use Named Volumes for Data Persistence

👉🏻 Named volumes ensure that data persists across container restarts.

👉🏻 Place volumes at the bottom of the file for better readability.

services:
  db:
    image: postgres:15
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:
Enter fullscreen mode Exit fullscreen mode

4. Leverage Environment Variables

👉🏻 Use environment variables for configuration, especially for secrets and service settings.

👉🏻 Use .env files to avoid hardcoding sensitive information in the Compose file.

services:
  api:
    image: node:20
    environment:
      - NODE_ENV=production
      - DB_HOST=${DB_HOST}
Enter fullscreen mode Exit fullscreen mode

5. Define Networks Explicitly

👉🏻 Use custom networks to manage how services communicate.

👉🏻 Isolate services to prevent unintended access between them.

networks:
  frontend:
  backend:

services:
  web:
    networks:
      - frontend
  db:
    networks:
      - backend
Enter fullscreen mode Exit fullscreen mode

6. Use Dependencies Carefully

👉🏻 Avoid strict dependencies when possible to reduce complexity.

👉🏻 Use depends_on when startup order is critical but consider alternatives like health checks.

services:
  web:
    depends_on:
      - db
Enter fullscreen mode Exit fullscreen mode

7. Apply Resource Limits (CPU & Memory)

👉🏻 Set resource constraints to prevent any service from monopolizing system resources.

services:
  api:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
Enter fullscreen mode Exit fullscreen mode

8. Use Profiles to Manage Development vs Production Configs

👉🏻 Profiles allow you to enable or disable services based on the environment.

services:
  debug:
    image: busybox
    profiles:
      - debug
Enter fullscreen mode Exit fullscreen mode
docker-compose --profile debug up
Enter fullscreen mode Exit fullscreen mode

9. Separate Configuration with Multiple Compose Files

👉🏻 Split configuration into multiple files (docker-compose.dev.yml, docker-compose.prod.yml) for different environments.

docker-compose -f docker-compose.yml -f docker-compose.prod.yml up
Enter fullscreen mode Exit fullscreen mode

10. Document Your Compose Files

👉🏻 Add comments to clarify configurations and make it easier for team members to understand.

# Web service running Node.js API
services:
  api:
    image: node:20
Enter fullscreen mode Exit fullscreen mode

Conclusion

Keeping your docker-compose.yml files scalable and unambiguous guarantees that your services will continue to be simple to administer during development and deployment. Your Docker-based apps will be more maintainable and scalable if you adhere to these best practices, which include resource restrictions, environment variables, and modular services. These guidelines will also aid in troubleshooting and swiftly onboarding new team members as your project expands.y.

Top comments (1)

Collapse
 
jangelodev profile image
João Angelo

Hi Wallace Freitas,
Thanks for sharing.