Docker Compose + Prodyml: The Definitive Playbook for Local Environment Management

Key Takeaways:

• Prodyml is a Ruby gem that automates docker-compose file generation from YAML configuration, allowing you to manage multiple environments without versioning bulky compose files in Git.
• By integrating Prodyml with Docker Compose, you can maintain a single source of truth for your application’s service definitions while keeping environment-specific secrets and variables in git-ignored files.
• This workflow significantly reduces merge conflicts and security risks associated with committing docker-compose.yml files that contain hardcoded credentials or environment-specific IP addresses.

Why Combine Prodyml with Docker Compose?

Most development teams struggle with the tension between reproducibility (needing identical environments) and secrecy (needing different credentials per environment). Standard Docker Compose files are excellent for definition but poor for configuration when they contain sensitive data.

Prodyml solves this by acting as a template engine for your compose files. Instead of committing docker-compose.yml, you commit prodyml.yml (the template) and generate the actual docker-compose.yml locally.

The Core Problem It Solves

• Git Bloat: No massive docker-compose.yml files checked into version control.
• Security: Secrets remain in local, git-ignored configuration files.
• Consistency: Every developer generates the exact same docker-compose.yml structure based on the shared template.

Step-by-Step Implementation Playbook

Step 1: Prerequisites

• Docker Engine and Docker Compose v2 installed.
• Ruby installed (Prodyml is a Ruby gem).
• Bundler installed.

Step 2: Initialize Prodyml

Create the configuration files that Prodyml will use to generate your compose file.

• Create prodyml.yml in your project root.
• This file defines the structure of your services, networks, and volumes.
• It uses Ruby ERB syntax to inject variables.

Example prodyml.yml:

version: "3.8"
services:
  app:
    image: myapp:latest
    ports:
      - "<%= ENV.fetch('APP_PORT', 8080) %>:8080"
    environment:
      - DB_HOST=<%= ENV['DB_HOST'] %>
      - DB_USER=<%= ENV['DB_USER'] %>
volumes:
  db_data:

Step 3: Create Local Secrets Configuration

Create a file that holds your environment-specific values. This file must be added to .gitignore.

• Create .prodyml or prodyml.local.yml.
• Add your secrets: DB_USER=dev_user, DB_HOST=192.168.1.5, etc.
• Ensure .gitignore includes prodyml.local.yml and docker-compose.yml.

Step 4: Generate the Compose File

Run Prodyml to render the template into a valid docker-compose.yml.

• Run: bundle exec prodyml build
• Verify that docker-compose.yml is generated in the root.
• Run: docker compose config to validate syntax.
• Run: docker compose up -d to start your environment.

Comparison: Traditional vs. Prodyml Workflow

Feature	Traditional Docker Compose	Docker Compose + Prodyml
Version Control	docker-compose.yml is committed to Git	prodyml.yml is committed; docker-compose.yml is git-ignored
Secrets Management	Risk of hardcoding secrets or managing complex .env files	Secrets stay in local, untracked config files
Multi-Environment	Requires -f flags or multiple compose files	Swap local config files; regenerate compose file
Setup Complexity	Low	Medium (requires Ruby/Bundler)
Merge Conflicts	High (if team edits compose files)	Low (only prodyml template is shared)

Validation Checklist

Before merging changes to prodyml.yml, verify the following:

• ✅ prodyml.yml is valid YAML and uses correct ERB syntax.
• ✅ All new environment variables are documented in prodyml.example.yml or README.
• ✅ docker-compose.yml is not in the Git status list (should be git-ignored).
• ✅ Running bundle exec prodyml build succeeds without errors.
• ✅ Running docker compose config validates the generated file.
• ✅ Sensitive values (passwords, API keys) are not present in prodyml.yml.

FAQ

Can I use Prodyml with Docker Compose v1?

No. Prodyml generates files compatible with Docker Compose v2 (the CLI plugin). If you are stuck on the legacy standalone docker-compose binary, consider migrating to the Docker CLI plugin first, as v1 is deprecated and no longer receiving updates.

What if I don’t want to use Ruby?

Prodyml is Ruby-centric. If your team avoids Ruby, consider alternatives like envsubst with standard Docker Compose variables, or tools like Docker Buildx with build arguments. However, Prodyml offers more granular control over the entire compose file structure, not just variable substitution.

How do I handle per-developer unique configurations?

Use Prodyml’s local override feature. Maintain a global prodyml.yml and a personal prodyml.local.yml. Configure Prodyml to merge both files during the build step. This allows each developer to override specific image tags or hostnames without affecting the shared template.