Docker Compose Deployments

Dokploy provides full support for Docker Compose, enabling you to deploy complex multi-container applications with a single configuration file. This is ideal for applications requiring multiple services like databases, caches, message queues, and background workers.

Creating a Compose Service

Add Compose Service

Navigate to your project
Click “Add Service” → “Compose”
Enter a name for your compose setup

Choose Source Type

Select how to provide your docker-compose.yml:

GitHub/GitLab/Bitbucket/Gitea: Load from Git repository
Custom Git: Use any Git repository URL
Raw: Paste docker-compose.yml content directly

Configure & Deploy

Provide compose file path or content
Set environment variables
Click “Deploy” to start all services

Source Types

Git Repository
Raw Compose

Load docker-compose.yml from a Git repository.

Configuration

# Repository structure
/
├── docker-compose.yml
├── app/
└── config/

Compose Path: Path to your docker-compose.yml file

docker-compose.yml (root)
docker/docker-compose.yml
deployments/production.yml

Dokploy clones the repository and uses the compose file at the specified path.

Paste your docker-compose.yml content directly into Dokploy.

version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  
  app:
    build: .
    environment:
      - NODE_ENV=production
    depends_on:
      - db
  
  db:
    image: postgres:15
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

This is ideal for templates or simple compose files that don’t require version control.

Compose Features

Service Loading

Dokploy automatically parses your docker-compose.yml and displays all services:

services:
  frontend:
    image: myapp/frontend:latest
    ports:
      - "3000:3000"
  
  backend:
    image: myapp/backend:latest
    ports:
      - "8000:8000"
  
  database:
    image: postgres:15

After deployment, you can:

View logs for individual services
Monitor resource usage per service
Access terminal for each service
Manage service-specific domains

Volume Mounts

Access and manage volumes for each service:

services:
  app:
    volumes:
      - app_data:/data
      - ./config:/etc/app/config:ro

volumes:
  app_data:

Dokploy displays:

Volume name and mount path
Volume type (named volume or bind mount)
Read/write permissions
Size and usage

Domain Management

Assign domains to specific services in your compose stack:

Add Domain

Navigate to Domains tab and add a domain for a specific service.

Configure Service

Select the target service from your compose file:

services:
  web:
    ports:
      - "80:80"  # This service can have a domain

Automatic Traefik Labels

Dokploy automatically injects Traefik labels for routing:

services:
  web:
    labels:
      - traefik.enable=true
      - traefik.http.routers.web.rule=Host(`example.com`)
      - traefik.http.services.web.loadbalancer.server.port=80

Advanced Configuration

Isolated Deployments

Enable isolated deployments to prevent service name conflicts:

# Original
services:
  web:
    container_name: web

# With isolation (Dokploy transforms to)
services:
  web:
    container_name: myapp-abc123-web

Isolated deployments append a unique suffix to all service names, networks, and volumes.

Randomize Compose

Generate unique service names with a custom suffix:

# Original service name
myapp-web

# With suffix "staging"
myapp-staging-web

# With suffix "pr-123"
myapp-pr-123-web

Use this feature carefully as it creates new services rather than updating existing ones.

Environment Variables

Inject environment variables into all services:

# Dokploy Environment Variables (applies to all services)
NODE_ENV=production
DATABASE_URL=postgresql://user:pass@db:5432/mydb
REDIS_URL=redis://redis:6379

These are automatically available in all compose services:

services:
  app:
    environment:
      - NODE_ENV  # Uses value from Dokploy
      - DATABASE_URL
  
  worker:
    environment:
      - NODE_ENV  # Same value as app service
      - REDIS_URL

File Mounts

Add configuration files that get mounted into your services:

Create Mount

Go to Mounts tab
Click “Add Mount”
Specify file path and content

Example: Nginx Config

File Path: /etc/nginx/nginx.conf
Content:

user nginx;
worker_processes auto;

events {
  worker_connections 1024;
}

http {
  include /etc/nginx/mime.types;
  default_type application/octet-stream;
  
  server {
    listen 80;
    location / {
      proxy_pass http://app:3000;
    }
  }
}

Reference in Compose

services:
  nginx:
    image: nginx:latest
    volumes:
      - /etc/nginx/nginx.conf:/etc/nginx/nginx.conf:ro

Template Deployment

Dokploy offers pre-configured templates for popular stacks:

WordPress

WordPress + MySQL

Ghost

Ghost CMS + MySQL

N8N

Workflow automation

Plausible

Analytics platform

Metabase

Business intelligence

Appwrite

Backend as a Service

Using Templates

Browse Templates

Click “Deploy Template” when creating a compose service.

Select Template

Choose from available templates. Each includes:

Pre-configured docker-compose.yml
Environment variables with defaults
Required volume mounts
Domain configuration

Customize

Modify environment variables and configuration:

# Example: WordPress template variables
WORDPRESS_DB_NAME=wordpress
WORDPRESS_DB_USER=wordpress
WORDPRESS_DB_PASSWORD=<generated>

Deploy

Click deploy to launch the pre-configured stack.

Managing Compose Services

Starting & Stopping

Stop
Start
Restart (Deploy)

# Dokploy executes:
docker compose -p <project-name> stop

Stops all containers while preserving volumes and networks.

# Dokploy executes:
docker compose -p <project-name> start

Starts previously stopped containers.

# Dokploy executes:
docker compose -p <project-name> up -d --build

Rebuilds images and recreates containers.

Viewing Logs

Access logs for the entire stack or individual services:

All Services: View combined logs from all containers
Specific Service: Filter logs by service name
Real-time: Stream logs as they’re generated
History: Browse historical logs

Service Terminal

Execute commands inside running containers:

# Examples
sh
bash
rails console
npm run migrate

Compose File Processing

Domain Injection

When you add a domain to a service, Dokploy automatically injects Traefik labels: Original compose file:

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"

Processed by Dokploy:

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    labels:
      - traefik.enable=true
      - traefik.http.routers.web-myapp.rule=Host(`example.com`)
      - traefik.http.routers.web-myapp.entrypoints=web
      - traefik.http.services.web-myapp.loadbalancer.server.port=80
    networks:
      - dokploy-network

networks:
  dokploy-network:
    external: true

Network Configuration

Dokploy ensures all services can:

Communicate with each other
Access Traefik for routing
Connect to the dokploy-network

networks:
  dokploy-network:
    external: true
  internal:
    internal: true  # Private network for service-to-service communication

Deployment Commands

# Click "Show Command" to see the exact docker compose command
docker compose -p myapp-abc123 \
  -f /path/to/docker-compose.yml \
  --env-file /path/to/.env \
  up -d --build

Troubleshooting

Service Won’t Start

Check Logs

View service-specific logs for error messages:

Error: Port 80 already in use
Error: Cannot connect to database

Verify Environment Variables

Ensure all required variables are set:

DATABASE_URL=postgresql://...
REDIS_URL=redis://...

Check Dependencies

Verify depends_on relationships:

services:
  app:
    depends_on:
      - db  # Ensure db starts first

Port Conflicts

Avoid host port conflicts:

# ❌ Bad: Fixed host port
ports:
  - "80:80"

# ✅ Good: Let Docker assign
ports:
  - "80"  # Exposes on random host port

# ✅ Best: Use Traefik for routing (no host ports)
labels:
  - traefik.enable=true
networks:
  - dokploy-network

Volume Permissions

Handle permission issues with bind mounts:

services:
  app:
    volumes:
      - ./data:/app/data
    user: "1000:1000"  # Match host user ID

Best Practices

Use Named Volumes

Prefer named volumes over bind mounts for data persistence:

volumes:
  - db_data:/var/lib/postgresql/data

Health Checks

Define health checks for services:

healthcheck:
  test: ["CMD", "pg_isready"]
  interval: 10s
  timeout: 5s
  retries: 5

Resource Limits

Set memory and CPU limits:

deploy:
  resources:
    limits:
      memory: 512M
      cpus: '0.5'

Dependency Order

Use depends_on with conditions:

depends_on:
  db:
    condition: service_healthy

Getting Started

Deployment

Databases

Infrastructure

Advanced

​Creating a Compose Service

​Source Types

​Configuration

​Compose Features

​Service Loading

​Volume Mounts

​Domain Management

​Advanced Configuration

​Isolated Deployments

​Randomize Compose

​Environment Variables

​File Mounts

​Template Deployment

WordPress

Ghost

N8N

Plausible

Metabase

Appwrite

​Using Templates

​Managing Compose Services

​Starting & Stopping

​Viewing Logs

​Service Terminal

​Compose File Processing

​Domain Injection

​Network Configuration

​Deployment Commands

​Troubleshooting

​Service Won’t Start

​Port Conflicts

​Volume Permissions

​Best Practices

Use Named Volumes

Health Checks

Resource Limits

Dependency Order

​Next Steps

Environment Variables

Applications

Build docs developers (and LLMs) love

Creating a Compose Service

Source Types

Configuration

Compose Features

Service Loading

Volume Mounts

Domain Management

Advanced Configuration

Isolated Deployments

Randomize Compose

Environment Variables

File Mounts

Template Deployment

Using Templates

Managing Compose Services

Starting & Stopping

Viewing Logs

Service Terminal

Compose File Processing

Domain Injection

Network Configuration

Deployment Commands

Troubleshooting

Service Won’t Start

Port Conflicts

Volume Permissions

Best Practices

Next Steps