Skip to content
QuantCDN

Importing Docker Compose Files

Quant Cloud supports importing standard docker-compose.yml files, allowing you to leverage your existing Docker Compose definitions with minimal changes. The platform automatically translates compose syntax into optimized cloud configurations.

Supported Docker Compose Features

Section titled “Supported Docker Compose Features”

Service-Level Configuration

Section titled “Service-Level Configuration”

Image

Section titled “Image”
services:
  web:
    image: nginx:latest          # External image
  app:
    image: latest                # Internal ECR (tag only)

Commands and Entrypoints

Section titled “Commands and Entrypoints”
services:
  app:
    command: ["php", "artisan", "queue:work"]
    # OR
    command: php artisan queue:work


    entrypoint: ["/usr/local/bin/entrypoint.sh"]
    # OR
    entrypoint: /usr/local/bin/entrypoint.sh

Supports both string and array formats.

Environment Variables

Section titled “Environment Variables”
services:
  app:
    environment:
      - DATABASE_HOST=mysql
      - DATABASE_PORT=3306
    # OR
    environment:
      DATABASE_HOST: mysql
      DATABASE_PORT: 3306

Supports both array and object formats.

Port Exposure

Section titled “Port Exposure”
services:
  web:
    ports:
      - "80"        # Container port only
      - "8080:80"   # Host:container mapping

Volume Mounts

Section titled “Volume Mounts”
volumes:
  db-data:
  uploads:


services:
  db:
    volumes:
      - db-data:/var/lib/mysql
      - uploads:/var/www/html/uploads

Referenced volumes are automatically created as EFS logical volumes if they don’t exist.

Container Dependencies

Section titled “Container Dependencies”
services:
  app:
    depends_on:
      - db
      - redis
    # OR with conditions
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started

Supported conditions: START, HEALTHY, COMPLETE, SUCCESS

Health Checks

Section titled “Health Checks”
services:
  web:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s

Working Directory and User

Section titled “Working Directory and User”
services:
  app:
    working_dir: /app
    user: "1000:1000"

Resource Configuration

Section titled “Resource Configuration”

Using Standard Deploy Syntax:

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 2048M
        reservations:
          memory: 1024M
      replicas: 2

Using Quant Labels:

services:
  app:
    labels:
      - "quant.cpu=1024"
      - "quant.memory=2048"
      - "quant.memory.reservation=1024"

Top-Level Configuration

Section titled “Top-Level Configuration”

Task-Level Resources

Section titled “Task-Level Resources”
x-quant-labels:
  quant.task.cpu: "2048"      # Total vCPU (1024 = 1 vCPU)
  quant.task.memory: "4096"   # Total memory in MiB
  quant.architecture: "ARM64" # ARM64 or X86_64

Volume Definitions

Section titled “Volume Definitions”
volumes:
  db-data:
  cache-data:

Automatically created as EFS logical volumes with default paths.

Unsupported Features

Section titled “Unsupported Features”
  • build directives (use pre-built images)
  • networks (automatic service discovery provided)
  • secrets (use Quant Cloud secrets management)
  • configs (use environment variables or volumes)
  • Host network mode, privileged mode, device mappings

Service Filtering

Section titled “Service Filtering”

Exclude services from import:

services:
  local-only:
    image: mailhog/mailhog
    labels:
      - "quant.type=none"

Resource Limits

Section titled “Resource Limits”

Task-level CPU and memory must follow the below combinations:

CPU (units)vCPUMemory Options (MiB)
2560.25512, 1024, 2048
5120.51024, 2048, 3072, 4096
102412048-8192 (1024 MiB increments)
204824096-16384 (1024 MiB increments)
409648192-30720 (1024 MiB increments)

Invalid values are automatically adjusted with warnings.

Complete Example

Section titled “Complete Example”
version: "3.8"


x-quant-labels:
  quant.task.cpu: "2048"
  quant.task.memory: "4096"
  quant.architecture: "X86_64"


volumes:
  db-data:
  uploads:


services:
  web:
    image: nginx:latest
    ports:
      - "80"
      - "443"
    labels:
      - "quant.cpu=1024"
      - "quant.memory=2048"
    volumes:
      - uploads:/var/www/html/uploads:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    depends_on:
      app:
        condition: service_healthy


  app:
    image: php:8.2-fpm
    command: ["php-fpm", "-F"]
    working_dir: /var/www/html
    user: "www-data"
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1024M
    volumes:
      - uploads:/var/www/html/uploads
    environment:
      DB_HOST: db
      REDIS_HOST: redis
    depends_on:
      - db
      - redis


  db:
    image: mysql:8.0
    volumes:
      - db-data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5


  redis:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]

Image Tag Suffixing

Section titled “Image Tag Suffixing”

For feature branch deployments, append a suffix to internal image tags:

# Query parameter or JSON wrapper
imageSuffix: "feature-xyz"


# Transforms internal images
# "latest" becomes "web-feature-xyz"
# External images unchanged: "nginx:latest" stays "nginx:latest"

Perfect for PR previews and feature branch environments.

What Happens During Import

Section titled “What Happens During Import”
  1. Parse & Validate - YAML syntax and structure validation
  2. Translate - Convert to Quant Cloud’s internal format
  3. Volume Creation - Auto-create any missing volumes
  4. Task Definition - Generate ECS task definition
  5. Deploy - Update service and trigger deployment

API Reference

Section titled “API Reference”

Import Endpoint:

Terminal window
POST /organizations/{orgName}/apps/{appName}/environments/{envName}/compose/import

Validation Endpoint (dry-run):

Terminal window
POST /organizations/{orgName}/apps/{appName}/environments/{envName}/compose/import/validate

Example:

Terminal window
curl -X POST \
  -H "X-Api-Secret: your-api-key" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @docker-compose.yml \
  https://dashboard.quantcdn.io/v3/organizations/my-org/apps/my-app/environments/production/compose/import

Best Practices

Section titled “Best Practices”
  1. Start Simple - Test with basic compose files first
  2. Specify Resources - Always define x-quant-labels for CPU/memory
  3. Use Health Checks - Enable zero-downtime deployments
  4. Validate Locally - Run docker-compose config before importing
  5. Version Images - Use specific tags in production
  6. Use Secrets Management - Don’t hardcode credentials

Troubleshooting

Section titled “Troubleshooting”

“Invalid CPU/memory combination”

  • Check permitted combinations table above
  • Platform auto-corrects with warnings

“Volume not found”

  • Volumes auto-create with default paths
  • Create manually for custom paths

“Image not accessible”

  • Verify internal tags exist in ECR
  • Check external image names are correct

“Port mapping conflicts”

  • Ensure unique ports across containers

Additional Resources

Section titled “Additional Resources”