Skip to main content
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:
1

Navigate to Projects

Click “Projects” in the sidebar
2

Create New Project

Click “Create Project” button
3

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

1

Open Project

Navigate to your project
2

Create Environment

Click “Create Environment”
3

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:
1

Trigger

Deployments start from:
  • Manual deploy button
  • Git push (with auto-deploy enabled)
  • Webhook trigger
  • API call
2

Build

For applications:
  • Clone source code
  • Install dependencies
  • Build artifacts
  • Create Docker image
  • Push to registry (if configured)
3

Deploy

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

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:
  1. Creates routing rules
  2. Obtains SSL certificate (if HTTPS enabled)
  3. Configures load balancing
  4. 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

​
Next Steps

Deploy an Application

Put these concepts into practice with our quickstart guide

Advanced Features

Explore backups, templates, monitoring, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us