Docker Compose - Dokploy

Docker Compose deployments allow you to run multi-container applications defined in a docker-compose.yml file. This is ideal for complex applications that require multiple services working together.

What is Docker Compose?

Docker Compose is a tool for defining and running multi-container Docker applications. With Dokploy, you can deploy entire application stacks that include:

Multiple interconnected services
Databases and caching layers
Message queues and background workers
Reverse proxies and load balancers
Any combination of containerized services

Multi-Service

Deploy multiple containers that work together as a single application stack.

Service Dependencies

Define relationships and dependencies between services.

Shared Networks

Services automatically share a network for seamless communication.

Templates

Use pre-built templates for popular application stacks.

Compose vs Stack Mode

Dokploy supports two deployment modes for Docker Compose:

docker-compose
stack

Standard Docker Compose mode using docker compose CLI:

Suitable for single-server deployments
Simpler configuration
Direct mapping of compose file features
Recommended for most use cases

Docker Swarm stack mode using docker stack deploy:

Enables multi-node deployments
High availability features
Load balancing across nodes
Requires Docker Swarm mode
Advanced orchestration features

Creating a Compose Deployment

Compose deployments are created within environments, similar to applications and databases.

Basic Configuration

name

string

required

Display name for your compose deployment

appName

string

required

Unique internal identifier (auto-generated if not provided)

description

string

Optional description to help identify the deployment’s purpose

composeFile

string

required

The complete docker-compose.yml content

composeType

enum

default:"docker-compose"

Deployment mode: docker-compose or stack

environmentId

string

required

The environment where this compose deployment will be created

Source Types

Compose deployments support multiple source options:

Git Repositories

GitHub
GitLab
Bitbucket
Custom Git

Deploy from GitHub repositories:

repository

string

required

Repository name (e.g., myorg/myrepo)

owner

string

required

Repository owner or organization

branch

string

required

Branch to deploy from

composePath

string

default:"./docker-compose.yml"

Path to the compose file in the repository

Raw Compose File

Paste or upload your docker-compose.yml content directly:

version: '3.8'

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
  
  api:
    image: node:18-alpine
    command: npm start
    environment:
      - NODE_ENV=production
    depends_on:
      - db
  
  db:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=secret
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

Environment Variables

Compose deployments support environment variable substitution:

Setting Variables

# Format: KEY=value (one per line)
NODE_ENV=production
API_KEY=your-secret-key
DATABASE_URL=postgresql://user:pass@db:5432/mydb
REDIS_URL=redis://redis:6379

Using Variables in Compose File

services:
  api:
    image: myapp:latest
    environment:
      - NODE_ENV=${NODE_ENV}
      - API_KEY=${API_KEY}
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}

Variables from the environment and project levels are automatically inherited. Compose-level variables take precedence.

Isolated Deployments

Dokploy supports isolated compose deployments, which modify service names to enable multiple instances:

isolatedDeployment

boolean

default:false

Enable isolated deployment mode

suffix

string

Suffix to append to service names (auto-generated if not provided)

How It Works

When isolated deployments are enabled:

Service names get a unique suffix: web becomes web-abc123
Container names are similarly modified
Networks are isolated per deployment
Volume names can be isolated (optional)

This allows running multiple instances of the same compose stack side-by-side.

Example

Original compose file:

services:
  web:
    image: nginx:alpine

With isolated deployment (suffix: abc123):

services:
  web-abc123:
    image: nginx:alpine
    container_name: web-abc123

Randomization

Randomization automatically generates unique identifiers for services:

randomize

boolean

default:false

Enable service name randomization

Use randomization carefully as it changes service discovery names. Applications must be designed to handle dynamic service names.

Domain Configuration

Compose deployments can have multiple domains configured for routing traffic to specific services:

Adding Domains

{
  host: "app.example.com",
  serviceName: "web",        // Target service in compose file
  port: 80,
  path: "/",
  https: true,
  certificateType: "letsencrypt"
}

Multiple Services, Multiple Domains

[
  {
    host: "app.example.com",
    serviceName: "web",
    port: 80,
    https: true
  },
  {
    host: "api.example.com",
    serviceName: "api",
    port: 3000,
    https: true
  }
]

See Domains & Routing for detailed information.

File Mounts

Inject configuration files into your compose deployment:

{
  type: "file",
  filePath: "/app/config/settings.json",
  content: JSON.stringify({
    api: {
      baseUrl: "https://api.example.com",
      timeout: 30000
    }
  }),
  serviceId: composeId,
  serviceType: "compose"
}

Automatic Deployments

autoDeploy

boolean

default:true

Automatically deploy when changes are pushed to the repository

triggerType

enum

default:"push"

When to trigger deployments: push or pull_request

watchPaths

array

Only trigger deployments when specific paths change

Watch Paths Example

watchPaths: [
  "docker-compose.yml",
  "services/**",
  ".env.example"
]

Deploying Templates

Dokploy provides pre-built templates for popular application stacks:

Available Templates

Fetch available templates:

GET /api/compose.templates

Templates include:

WordPress + MySQL
Ghost + MySQL
Nextcloud + PostgreSQL
GitLab + PostgreSQL + Redis
Directus + PostgreSQL
And many more…

Deploying a Template

POST /api/compose.deployTemplate
{
  environmentId: "env_123",
  serverId: "server_456",    // Optional for cloud deployments
  id: "wordpress",            // Template ID
  baseUrl: "..."              // Optional custom template repository
}

Templates automatically configure:

Environment variables with secure defaults
Persistent volume mounts
Domain configuration
Service dependencies

Managing Services

View and manage individual services within your compose deployment:

Loading Services

GET /api/compose.loadServices
{
  composeId: "compose_123",
  type: "code" | "running"    // From compose file or running containers
}

Returns service information:

Service names
Image names
Port mappings
Environment variables
Volume mounts
Network configuration

Service Volumes

View volume mounts for a specific service:

GET /api/compose.loadMountsByService
{
  composeId: "compose_123",
  serviceName: "web"
}

Deployment Operations

Manual Deployment

Trigger a deployment manually:

POST /api/compose.deploy
{
  composeId: "compose_123",
  title: "Manual deployment",
  description: "Deploying latest changes"
}

Rebuild Deployment

Rebuild without fetching latest code:

POST /api/compose.redeploy
{
  composeId: "compose_123",
  title: "Rebuild",
  description: "Rebuilding with same code"
}

Start/Stop

Control the compose stack:

// Start all services
POST /api/compose.start
{ composeId: "compose_123" }

// Stop all services
POST /api/compose.stop
{ composeId: "compose_123" }

Advanced Features

Custom Commands

Override the default docker compose command:

command

string

Custom command to append to docker compose

Example:

command: "up -d --build --force-recreate"

Submodule Support

enableSubmodules

boolean

default:false

Clone Git submodules when fetching repository

Fetch Source Type

Load the latest compose file from the repository:

POST /api/compose.fetchSourceType
{
  composeId: "compose_123"
}

This clones the repository and loads the compose file without deploying.

Get Converted Compose

Get the final compose file with all transformations applied (variables substituted, domains added, etc.):

GET /api/compose.getConvertedCompose
{
  composeId: "compose_123"
}

Importing Templates

Import custom templates or configurations:

POST /api/compose.import
{
  composeId: "compose_123",
  base64: "base64_encoded_template_data"
}

The template data should include:

Docker compose file content
Configuration (environment variables, domains, mounts)

Database Schema

Compose deployments are stored with the following structure:

interface Compose {
  composeId: string;
  name: string;
  appName: string;
  description?: string;
  environmentId: string;
  
  // Source configuration
  sourceType: "github" | "gitlab" | "bitbucket" | "gitea" | "git" | "raw";
  composeFile: string;
  composePath: string;
  composeType: "docker-compose" | "stack";
  
  // Git configuration
  repository?: string;
  owner?: string;
  branch?: string;
  autoDeploy: boolean;
  triggerType: "push" | "pull_request";
  watchPaths?: string[];
  
  // Deployment configuration
  env?: string;
  command: string;
  suffix: string;
  randomize: boolean;
  isolatedDeployment: boolean;
  
  // Status
  composeStatus: "idle" | "running" | "done" | "error";
  
  // Metadata
  serverId?: string;
  createdAt: string;
}

Monitoring & Logs

Deployment Logs

View logs for the deployment process:

Service build output
Pull progress
Container startup logs
Error messages

Service Logs

Access logs for individual services:

# View logs for a specific service
docker compose -p {appName} logs -f {serviceName}

Resource Usage

Monitor resource consumption for all services in the stack:

Combined CPU usage
Total memory usage
Network traffic
Disk I/O

Best Practices

Pin Image Versions

Always use specific image tags instead of latest to ensure reproducible deployments:

# Good
image: postgres:16.1

# Avoid
image: postgres:latest

Use Health Checks

Define health checks for services to ensure proper startup order and monitoring:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

Organize with Labels

Use labels to organize and document your services:

labels:
  - "com.example.description=Main web server"
  - "com.example.department=engineering"
  - "[email protected]"

Use Isolated Deployments for Testing

Enable isolated deployments when you need to test changes without affecting production.

Keep Secrets Secure

Never commit secrets to your compose file. Use environment variables instead:

environment:
  - DB_PASSWORD=${DB_PASSWORD}
  - API_KEY=${API_KEY}

Troubleshooting

Services Won’t Start

Check the deployment logs for error messages
Verify all required environment variables are set
Ensure image names are correct and accessible
Check for port conflicts with other services

Service Communication Issues

Verify services are on the same network
Use service names (not container names) for communication
Check firewall rules if accessing external services
Verify port mappings in your compose file

Volume Mount Problems

Ensure volume paths are correctly specified
Check file permissions in mounted directories
Verify volumes are created before containers start

Next Steps

Domains & Routing

Configure domains for your compose services

Templates

Explore available compose templates

Overview

Getting Started

Core Concepts

Deployments

Databases

Monitoring & Observability

Advanced Features

Configuration

CLI & Automation

Community & Support

​What is Docker Compose?

Multi-Service

Service Dependencies

Shared Networks

Templates

​Compose vs Stack Mode

​Creating a Compose Deployment

​Basic Configuration

​Source Types

​Git Repositories

​Raw Compose File

​Environment Variables

​Setting Variables

​Using Variables in Compose File

​Isolated Deployments

​How It Works

​Example

​Randomization

​Domain Configuration

​Adding Domains

​Multiple Services, Multiple Domains

​File Mounts

​Automatic Deployments

​Watch Paths Example

​Deploying Templates

​Available Templates

​Deploying a Template

​Managing Services

​Loading Services

​Service Volumes

​Deployment Operations

​Manual Deployment

​Rebuild Deployment

​Start/Stop

​Advanced Features

​Custom Commands

​Submodule Support

​Fetch Source Type

​Get Converted Compose

​Importing Templates

​Database Schema

​Monitoring & Logs

​Deployment Logs

​Service Logs

​Resource Usage

​Best Practices

​Troubleshooting

​Services Won’t Start

​Service Communication Issues

​Volume Mount Problems

​Next Steps

Domains & Routing

Templates

Build docs developers (and LLMs) love

What is Docker Compose?

Compose vs Stack Mode

Creating a Compose Deployment

Basic Configuration

Source Types

Git Repositories

Raw Compose File

Environment Variables

Setting Variables

Using Variables in Compose File

Isolated Deployments

How It Works

Example

Randomization

Domain Configuration

Adding Domains

Multiple Services, Multiple Domains

File Mounts

Automatic Deployments

Watch Paths Example

Deploying Templates

Available Templates

Deploying a Template

Managing Services

Loading Services

Service Volumes

Deployment Operations

Manual Deployment

Rebuild Deployment

Start/Stop

Advanced Features

Custom Commands

Submodule Support

Fetch Source Type

Get Converted Compose

Importing Templates

Database Schema

Monitoring & Logs

Deployment Logs

Service Logs

Resource Usage

Best Practices

Troubleshooting

Services Won’t Start

Service Communication Issues

Volume Mount Problems

Next Steps