Core Concepts

Dokploy organizes your infrastructure using a hierarchical structure that mirrors real-world development workflows. Understanding these core concepts will help you effectively use Dokploy to manage your applications and databases.

Architecture Overview

Dokploy uses a four-tier organizational hierarchy:

Organization
  └── Projects
        └── Environments
              └── Services (Applications, Databases, Compose)

Each level serves a specific purpose in organizing and isolating your infrastructure.

Organizations

An organization is the top-level entity in Dokploy. When you first install Dokploy, a default organization is created for you. Purpose: Organizations provide complete isolation between different tenants, companies, or business units. Use Cases:

Multi-tenant hosting platforms
Agency managing multiple clients
Enterprise divisions requiring complete separation

Most users work within a single organization. Multi-organization support is typically used in agency or enterprise scenarios.

Projects

Projects are the primary organizational unit for grouping related applications and services. Purpose: A project represents a product, application, or logical grouping of services that work together. Examples:

A SaaS product with frontend, backend, and database
An e-commerce platform with multiple microservices
A company website with staging and production versions

Key Features:

Can contain multiple environments
Project-level environment variables shared across all services
Isolated networking and resources

Creating a Project

From the Dokploy dashboard:

Navigate to Projects

Click “Projects” in the sidebar

Create New Project

Click “Create Project” button

Configure Project

Name: Descriptive name (e.g., “E-commerce Platform”)
Description: Optional details about the project
Environment Variables: Optional project-wide variables

Each new project automatically includes a default “Production” environment.

Environments

Environments represent different stages of your deployment pipeline within a project. Purpose: Separate development, staging, and production deployments with different configurations. Common Environments:

Production - Live, customer-facing services
Staging - Pre-production testing environment
Development - Active development and testing

Characteristics:

Each environment has isolated services and resources
Environment-specific variables (API keys, database credentials)
Independent deployment pipelines
Services within an environment can communicate via Docker networking

Environment Isolation

Services in different environments are completely isolated:

Project: E-commerce
  ├── Production Environment
  │     ├── frontend-app (app-production)
  │     ├── api-server (api-production)
  │     └── postgres-db (db-production)
  │
  └── Staging Environment
        ├── frontend-app (app-staging)
        ├── api-server (api-staging)  
        └── postgres-db (db-staging)

Each environment has its own:

Network namespace
Resource limits
Environment variables
Deployment history

Creating an Environment

Open Project

Navigate to your project

Create Environment

Click “Create Environment”

Configure

Name: Environment name (e.g., “Staging”)
Description: Optional description
Environment Variables: Variables shared across all services in this environment

Services

Services are the actual workloads running in your infrastructure. Dokploy supports three types of services:

1. Applications

Applications are your custom code deployed as containerized services. Source Types:

GitHub/GitLab/Bitbucket/Gitea - Deploy from Git repositories
Docker Registry - Deploy pre-built Docker images
Custom Git - Deploy from any Git repository via SSH
Dockerfile - Build from a Dockerfile in your repo
Drop - Upload and deploy source code directly

Build Types:

Nixpacks - Zero-config automatic builds (detects Node.js, Python, Go, etc.)
Dockerfile - Use your custom Dockerfile
Heroku Buildpacks - Heroku-compatible buildpacks
Paketo Buildpacks - Cloud Native Buildpacks
Railpack - Optimized Ruby on Rails builds
Static - Serve static sites (HTML/CSS/JS)

Configuration Options:

// Application properties (from application.ts schema)
{
  name: string;                    // Display name
  appName: string;                 // Unique identifier (DNS-safe)
  description?: string;            // Optional description
  env?: string;                    // Environment variables
  buildArgs?: string;              // Docker build arguments
  buildSecrets?: string;           // Build-time secrets
  
  // Resources
  memoryLimit?: string;            // e.g., "512m", "2g"
  memoryReservation?: string;
  cpuLimit?: string;               // e.g., "0.5", "2"
  cpuReservation?: string;
  
  // Git source
  repository?: string;
  owner?: string;
  branch?: string;
  buildPath?: string;              // Default: "/"
  
  // Build configuration  
  buildType: "nixpacks" | "dockerfile" | "heroku_buildpacks" | "paketo_buildpacks" | "static" | "railpack";
  dockerfile?: string;             // Default: "Dockerfile"
  dockerContextPath?: string;
  
  // Deployment
  replicas: number;                // Default: 1
  autoDeploy: boolean;             // Auto-deploy on git push
  command?: string;                // Override container command
  args?: string[];                 // Command arguments
}

Example: Node.js Application

Name: api-server
Source: GitHub
Repository: mycompany/api
Branch: main
Build Type: Nixpacks
Port: 3000
Replicas: 2
Auto Deploy: Enabled

2. Databases

Managed database services with automatic configuration. Supported Databases:

PostgreSQL (postgres:18) - Relational database
MySQL (mysql:8) - Popular relational database
MongoDB (mongo:8) - Document-oriented NoSQL
MariaDB (mariadb:11) - MySQL fork
Redis (redis:7) - In-memory cache and message broker

Configuration:

// Database properties (from postgres.ts schema)
{
  name: string;
  appName: string;                 // Service identifier
  databaseName: string;            // Database name to create
  databaseUser: string;            // Username
  databasePassword: string;        // Password
  dockerImage: string;             // e.g., "postgres:18"
  
  // Resources
  memoryLimit?: string;
  cpuLimit?: string;
  
  // Networking
  externalPort?: number;           // Expose on host (optional)
  
  // Storage
  volumes: [];                     // Persistent volumes
}

Connection Strings: Services in the same environment connect using service names:

# PostgreSQL
DATABASE_URL=postgresql://user:password@postgres-service:5432/dbname

# MySQL  
DATABASE_URL=mysql://user:password@mysql-service:3306/dbname

# MongoDB
MONGO_URL=mongodb://user:password@mongo-service:27017/dbname

# Redis
REDIS_URL=redis://redis-service:6379

The service name (e.g., postgres-service) is automatically used as the hostname within the Docker network.

3. Docker Compose

Deploy complex multi-container applications using Docker Compose files. Source Types:

GitHub/GitLab/Bitbucket/Gitea - Load compose file from repository
Raw - Paste compose file directly in the UI

Features:

Native docker-compose.yml support
Environment variable substitution
Volume management
Network configuration
Service dependencies

Example: WordPress with MySQL

version: '3.8'

services:
  wordpress:
    image: wordpress:latest
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: ${DB_USER}
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DB_NAME: ${DB_NAME}
    ports:
      - "8080:80"
    depends_on:
      - db
      
  db:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: ${DB_NAME}
      MYSQL_USER: ${DB_USER}
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Dokploy will:

Parse your compose file
Substitute environment variables
Deploy all services as a stack
Manage networking automatically

Deployments

Deployments are the process of building and running your services. Deployment Process:

Trigger

Deployments start from:

Manual deploy button
Git push (with auto-deploy enabled)
Webhook trigger
API call

Build

For applications:

Clone source code
Install dependencies
Build artifacts
Create Docker image
Push to registry (if configured)

Deploy

Pull Docker image (if not built locally)
Create/update Docker service
Configure networking (Traefik routing)
Apply environment variables
Start containers

Health Check

Monitor container startup
Verify service health
Update load balancer

Deployment Types:

// Deployment schema (from deployment.ts)
{
  title: string;                          // Deployment description
  status: "running" | "done" | "error" | "cancelled";
  logPath: string;                        // Path to deployment logs
  startedAt: string;                      // ISO timestamp
  finishedAt?: string;                    // ISO timestamp
  errorMessage?: string;                  // Error details if failed
}

Viewing Deployments: Each service has a “Deployments” tab showing:

Deployment history
Build logs
Deployment status
Duration
Git commit (for repository sources)

Docker Swarm Integration

Dokploy uses Docker Swarm for orchestration. Benefits:

Service discovery - Services find each other by name
Load balancing - Automatic request distribution
Rolling updates - Zero-downtime deployments
Self-healing - Automatic container restart on failure
Multi-node scaling - Deploy across multiple servers

Service Configuration:

// Swarm settings (from application.ts)
{
  replicas: number;                       // Number of container instances
  
  healthCheckSwarm?: {                    // Health check configuration
    test: string[];                       // Health check command
    interval: number;                     // Check interval (ns)
    timeout: number;                      // Timeout (ns)
    retries: number;                      // Retries before unhealthy
  };
  
  restartPolicySwarm?: {                  // Restart policy
    condition: "none" | "on-failure" | "any";
    delay: number;
    maxAttempts: number;
  };
  
  updateConfigSwarm?: {                   // Rolling update config
    parallelism: number;                  // Containers to update simultaneously  
    delay: number;                        // Delay between updates
    order: "start-first" | "stop-first";
  };
}

Traefik Integration

Traefik acts as the reverse proxy and load balancer. Automatic Features:

HTTP/HTTPS routing based on domains
SSL certificate generation (Let’s Encrypt)
Load balancing across replicas
Automatic service discovery
WebSocket support

Domain Configuration:

// Domain schema (from domain.ts)
{
  host: string;                           // Domain name
  path?: string;                          // URL path (default: "/")
  port: number;                           // Container port
  https: boolean;                         // Enable HTTPS
  certificateType: "letsencrypt" | "none" | "custom";
}

When you add a domain to a service, Traefik:

Creates routing rules
Obtains SSL certificate (if HTTPS enabled)
Configures load balancing
Updates automatically when service scales

Resource Management

Dokploy allows fine-grained resource control: CPU Limits:

cpuReservation: "0.5"    # Reserve 0.5 CPU cores
cpuLimit: "2"            # Maximum 2 CPU cores

Memory Limits:

memoryReservation: "512m"  # Reserve 512 MB
memoryLimit: "2g"          # Maximum 2 GB

Storage:

Persistent volumes for databases
Bind mounts for configuration files
Named volumes managed by Docker

Monitoring

Dokploy provides real-time monitoring:

CPU Usage - Per-service CPU consumption
Memory Usage - RAM usage and limits
Network I/O - Ingress/egress bandwidth
Storage - Disk usage per volume
Logs - Real-time and historical logs

Getting Started

Deployment

Databases

Infrastructure

Advanced

Architecture Overview

Organizations

Projects

Creating a Project

Environments

Environment Isolation

Creating an Environment

Services

1. Applications

2. Databases

3. Docker Compose

Deployments

Docker Swarm Integration

Traefik Integration

Resource Management

Monitoring

Next Steps

Deploy an Application

Advanced Features

Getting Started

Deployment

Databases

Infrastructure

Advanced

Documentation Index

​Architecture Overview

​Organizations

​Projects

​Creating a Project

​Environments

​Environment Isolation

​Creating an Environment

​Services

​1. Applications

​2. Databases

​3. Docker Compose

​Deployments

​Docker Swarm Integration

​Traefik Integration

​Resource Management

​Monitoring

​Next Steps

Deploy an Application

Advanced Features

Architecture Overview

Organizations

Projects

Creating a Project

Environments

Environment Isolation

Creating an Environment

Services

1. Applications

2. Databases

3. Docker Compose

Deployments

Docker Swarm Integration

Traefik Integration

Resource Management

Monitoring

Next Steps