Document Docker Compose Parsing and Transformation Process

[Cinzya]

Problem

Users deploying Docker Compose applications through Coolify currently lack comprehensive documentation explaining how Coolify processes their compose files before deployment. While the existing documentation explains how to use Docker Compose and what features are available, it doesn't explain what transformations Coolify applies behind the scenes.

This creates confusion when users notice their deployed containers have:

• Different container names than specified
• Additional labels they didn't add
• Modified volume paths
• Changes to networks and other configurations

Proposed Solution

Add documentation that explains the transformation process Coolify applies to user-provided compose files.

Key Topics to Cover:

1. Overview of the Parser

• Two-stage process: Parse user's compose → Generate final deployable compose
• Why Coolify transforms the compose file (management, networking, proxy integration)
• Mention of raw compose deployment mode as an opt-out

2. Container Name Transformations

• How Coolify renames containers: {service-name}-{application-uuid}
• Optional timestamp-based naming
• Preview deployment naming for PR deployments (-pr-{id} suffix)

3. Network Modifications

• Auto-generated base network ({uuid})
• How Coolify adds the proxy to the network
• Preview deployment network isolation

4. Volume Path Transformations

• How bind mounts are rewritten: /data/coolify/applications/{uuid}/...
• Named volume transformations: {uuid}_{volume-name}
• Preview deployment volume isolation (-pr-{id} suffix)

5. Label Additions

• Coolify management labels automatically added
• Proxy routing labels (Traefik/Caddy) auto-generated from domains
• How custom labels are preserved

6. Configuration Options Affecting Transformations

• Consistent container naming setting
• Label escape settings
• Custom docker run options and how they're converted

7. Before/After Examples
Simple examples showing:

• A basic compose file as written by the user
• The final deployed compose file after Coolify transformations
• Highlighting key changes (names, volumes, networks, labels)

Benefits

• Reduces Support Questions: Users understand what happens to their compose files
• Better Debugging: Users can troubleshoot by understanding the transformations
• Informed Decisions: Users understand when to use raw vs normal compose deployment
• Transparency: Shows the value Coolify adds (auto-networking, proxy integration, management labels)

Suggested Location

Either:

• Add new section to existing /knowledge-base/docker/compose - Extend current compose documentation
• Create new page /knowledge-base/docker/compose-parser - Separate page titled "Coolify Compose Parser"

Both would complement existing documentation:

• /knowledge-base/docker/compose - Docker Compose features and usage
• /applications/build-packs/docker-compose - How to set up the build pack