---
description:
globs:
alwaysApply: true
---
Docker Compose Deployment in Coolify API
How Docker Compose Deployment Works
Docker Compose deployment in Coolify operates through a dedicated API endpoint that handles the creation and deployment of applications based on Docker Compose files. The process follows these key steps:
API Endpoint and Request Structure
The primary endpoint for Docker Compose deployments is POST /applications/dockercompose ApplicationsController.php:670-732 . This endpoint requires specific mandatory fields including project_uuid, server_uuid, environment_name or environment_uuid, and docker_compose_raw ApplicationsController.php:686-700 .
Base64 Encoding Requirement
A critical requirement for Docker Compose deployment is that the docker_compose_raw field must be base64 encoded ApplicationsController.php:1414-1431 . The system validates this encoding and will reject requests with improperly encoded content.
Validation Process
Coolify implements comprehensive validation for Docker Compose files using the validateComposeFile function docker.php:1056-1090 . This function creates a temporary file on the server, uses Docker's built-in validation through docker compose config, and ensures the compose file syntax is correct before proceeding with deployment.
Deployment Processing
After successful validation, the system uses the LoadComposeFile action to process the compose file LoadComposeFile.php:8-16 . For applications deployed from Git repositories, the system can load compose files directly from the repository using sparse checkout techniques Application.php:1359-1450 .
Recommended Docker Compose File Syntax
Basic Service Structure
Coolify follows standard Docker Compose syntax with additional conventions for optimal integration. A recommended basic structure includes services with proper environment variable handling documenso.yaml:7-48 .
Special Environment Variables
Coolify uses special environment variable patterns that are automatically processed during deployment:
SERVICE_FQDN_* for domain configuration
SERVICE_PASSWORD_* for automatic password generation
SERVICE_USER_* for user credentials
SERVICE_BASE64_* for base64-encoded secrets documenso.yaml:13-28
Health Check Configuration
Health checks are strongly recommended and should follow Docker Compose standards with appropriate test commands, intervals, and retry configurations documenso.yaml:29-48 .
Volume and Bind Mount Syntax
Coolify supports both standard volumes and bind mounts with special content injection capabilities for configuration files filebrowser.yaml:12-31 .
Service Dependencies
Dependencies between services should be properly defined using depends_on with appropriate conditions like service_healthy documenso.yaml:10-12 .
Deployment Workflow
API Request Processing
The deployment process begins with API request validation through the create_application method with type 'dockercompose' ApplicationsController.php:1378-1450 . The system creates a Service model rather than an Application model for Docker Compose deployments.
Instant Deployment Option
The API supports an instant_deploy parameter that can trigger immediate deployment after successful creation ApplicationsController.php:1446-1448 .
Background Job Processing
Actual deployment is handled by background jobs that process the compose file, generate appropriate Docker commands, and manage the deployment lifecycle through the ApplicationDeploymentJob ApplicationDeploymentJob.php:39-100 .
Notes
Docker Compose deployment in Coolify requires careful attention to the base64 encoding requirement and proper use of Coolify's special environment variable patterns. The system provides robust validation and supports both immediate and queued deployment options. Templates in the repository serve as excellent examples of recommended syntax and patterns for successful deployments.
