Deployments Overview

Overview

Dokploy provides flexible deployment workflows that support multiple source types, build methods, and deployment strategies. Deploy from Git repositories, Docker registries, or direct file uploads with automated builds and rollback capabilities.

Deployment Workflow

Every deployment in Dokploy follows a consistent lifecycle:

Source Retrieval

Dokploy fetches your application code from:

Git repository (GitHub, GitLab, Bitbucket, Gitea, or custom Git)
Docker registry (pre-built images)
Direct upload (ZIP file drop)

Build Phase

Your application is built using one of:

Nixpacks - Auto-detect framework and build
Dockerfile - Custom Docker build
Heroku Buildpacks - Heroku-compatible builds
Paketo Buildpacks - Cloud Native Buildpacks
Railpack - Optimized for Ruby on Rails
Static - Static site generation

Image Creation

A Docker image is created and optionally pushed to a registry:

myapp:latest
# or with registry
registry.example.com/myapp:latest

Container Deployment

The image is deployed as a Docker Swarm service with:

Environment variables
Volume mounts
Port mappings
Resource limits
Health checks

Health Verification

Dokploy verifies the deployment:

Container starts successfully
Health checks pass (if configured)
Application responds on configured port

Deployment Types

Manual Deployment

Trigger deployments manually from the Dokploy dashboard.

curl -X POST https://your-domain.com/api/trpc/application.deploy \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app-123",
    "title": "Manual deployment",
    "description": "Deploying latest changes"
  }'

Use cases:

Initial deployment
Testing before automation
Emergency hotfixes
Rollback to specific version

Automatic Deployment

Deploy automatically when code changes are pushed to your repository. Trigger types:

Push - Deploy on every push to the configured branch
Tag - Deploy only when new Git tags are created
Pull Request - Create preview deployments for PRs

Automatic deployments require webhook configuration. See Git Integration for setup instructions.

Rebuild Deployment

Rebuild an application without fetching new code from the repository.

curl -X POST https://your-domain.com/api/trpc/application.redeploy \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app-123",
    "title": "Rebuild deployment",
    "description": "Rebuilding with updated environment variables"
  }'

Use cases:

Environment variable changes
Build configuration updates
Clear cache and rebuild
Apply new base image updates

Drop Deployment

Upload and deploy a ZIP file directly without Git integration.

const formData = new FormData();
formData.append('zip', zipFile);
formData.append('applicationId', 'app-123');
formData.append('dropBuildPath', '/');

await fetch('https://your-domain.com/api/trpc/application.dropDeployment', {
  method: 'POST',
  headers: { 'x-api-key': process.env.API_KEY },
  body: formData
});

Use cases:

Quick prototypes
Closed-source applications
Build artifacts from CI/CD
Temporary deployments

Deployment States

Applications transition through different states during deployment:

idle

No deployment in progress. Application is stopped or ready to deploy.

running

Deployment in progress. Building or starting the application.

done

Deployment completed successfully. Application is running.

error

Deployment failed. Check logs for error details.

Deployment History

Dokploy maintains a complete history of all deployments:

// Get deployment history for an application
const deployments = await fetch(
  'https://your-domain.com/api/trpc/deployment.all?applicationId=app-123',
  { headers: { 'x-api-key': process.env.API_KEY } }
);

Each deployment record includes:

string

Unique deployment identifier

string

Deployment title (e.g., commit message)

string

Additional deployment details (e.g., commit hash)

enum

Deployment status: running, done, error, cancelled

string

Path to deployment logs for debugging

string

Deployment timestamp

number

Process ID of the deployment job (for cancellation)

Deployment Logs

All deployment output is streamed to logs in real-time:

# View deployment logs
tail -f /var/lib/dokploy/logs/app-123/deployment-456.log

Log format:

[01] Cloning repository from github.com/user/repo...
[02] ✓ Repository cloned successfully
[03] Applying patches...
[04] Building with Nixpacks...
[05] ✓ Build completed successfully
[06] Creating Docker image: myapp:latest
[07] ✓ Image created
[08] Starting container...
[09] ✓ Container started
[10] ✓ Deployment complete!

Logs are preserved even after deployment completion for debugging and auditing.

Queue Management

Dokploy uses a job queue to manage concurrent deployments:

// View deployment queue
const queue = await fetch(
  'https://your-domain.com/api/trpc/deployment.queueList',
  { headers: { 'x-api-key': process.env.API_KEY } }
);

Queue states:

waiting - Job is queued but not started
active - Job is currently executing
completed - Job finished successfully
failed - Job failed with errors
delayed - Job is scheduled for later

Cancelling Deployments

Cancel a running deployment:

curl -X POST https://your-domain.com/api/trpc/application.cancelDeployment \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app-123"}'

Cancelling a deployment may leave the application in an inconsistent state. Consider redeploying after cancellation.

Rollback Deployments

Dokploy supports rolling back to previous deployments:

Enable Rollback

await fetch('https://your-domain.com/api/trpc/application.update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.API_KEY
  },
  body: JSON.stringify({
    applicationId: 'app-123',
    rollbackActive: true,
    rollbackRegistryId: 'registry-123'  // Registry to store rollback images
  })
});

Perform Rollback

Navigate to Deployments tab
Find the previous successful deployment
Click Rollback button
Confirm rollback action

Rollback images are automatically tagged and stored in the configured rollback registry.

Multi-Server Deployments

Deploy applications across multiple servers:

{
  "applicationId": "app-123",
  "serverId": "server-456",        // Deployment target server
  "buildServerId": "server-789"    // Build server (optional)
}

Benefits:

Centralized builds - Build on powerful servers
Edge deployment - Deploy close to users
Resource isolation - Separate build and runtime
Multi-region - Deploy globally

Multi-server deployments are available in Dokploy Cloud. Self-hosted instances support single-server deployments.

Build Caching

Speed up deployments with build caching:

Enable Cache

{
  "applicationId": "app-123",
  "cleanCache": false  // Keep build cache
}

Clear Cache

curl -X POST https://your-domain.com/api/trpc/application.clearDeployments \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app-123"}'

Cache benefits:

Faster dependency installation
Reduced network bandwidth
Lower build times
Improved consistency

Clear cache if you encounter build issues or need to force fresh installations.

Deployment Notifications

Receive notifications about deployment events:

Build Success

Notify when deployments complete successfully

Build Failure

Alert when deployments fail with error details

Application Down

Warn when applications stop unexpectedly

Health Check Failed

Alert when health checks fail repeatedly

See Notifications for setup instructions.

Best Practices

Build Configuration

Use Specific Base Images

# Bad - uses latest tag
FROM node:latest

# Good - pins specific version
FROM node:20.11.0-alpine

Pinning versions ensures consistent builds across deployments.

Optimize Build Context

# .dockerignore
node_modules
.git
.env
*.log
README.md

Exclude unnecessary files to speed up builds and reduce image size.

Multi-Stage Builds

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

Smaller images deploy faster and use less disk space.

Deployment Strategy

Test in Staging - Always test deployments in staging before production
Use Health Checks - Configure health checks for automatic recovery
Monitor Resources - Watch CPU and memory usage during deployments
Enable Rollback - Store previous images for quick rollback
Review Logs - Check deployment logs after each deployment

Security

Never Commit Secrets - Use environment variables for sensitive data
Scan Images - Enable vulnerability scanning on registries
Update Dependencies - Keep base images and packages updated
Minimize Permissions - Run containers with minimal privileges
Use Private Registries - Store proprietary images in private registries

Next Steps

Git Integration

Connect Git repositories and configure webhooks

Docker Registry

Configure registries for pulling and pushing images

Build Configuration

Customize build process and optimize builds

Environment Variables

Manage application configuration and secrets

First Deployment

Step-by-step deployment tutorial

Monitoring

Monitor deployments and application health

Troubleshooting

Deployment Stuck in Running State

Symptoms: Deployment shows running but never completesSolutions:

Check deployment logs for errors:
docker service logs dokploy
Verify sufficient disk space:
df -h

Kill stuck deployment process:

curl -X POST https://your-domain.com/api/trpc/deployment.killProcess \
  -H "x-api-key: your-api-key" \
  -d '{"deploymentId": "deploy-123"}'

Build Fails with Network Errors

Symptoms: Timeouts or connection refused errors during buildSolutions:

Check server internet connectivity
Verify DNS resolution

Configure HTTP proxy if behind firewall:

HTTP_PROXY=http://proxy.example.com:3128
HTTPS_PROXY=http://proxy.example.com:3128

Increase timeout limits in build configuration

Container Starts Then Immediately Stops

Symptoms: Deployment completes but application status shows errorSolutions:

Check application logs:
docker service logs myapp
Verify start command is correct
Ensure port configuration matches application
Check for missing environment variables
Verify database connectivity

​Overview

​Deployment Workflow

​Deployment Types

​Manual Deployment

​Automatic Deployment

​Rebuild Deployment

​Drop Deployment

​Deployment States

idle

running

done

error

​Deployment History

​Deployment Logs

​Queue Management

​Cancelling Deployments

​Rollback Deployments

​Enable Rollback

​Perform Rollback

​Multi-Server Deployments

​Build Caching

​Enable Cache

​Clear Cache

​Deployment Notifications

Build Success

Build Failure

Application Down

Health Check Failed

​Best Practices

​Build Configuration

​Deployment Strategy

​Security

​Next Steps

Git Integration

Docker Registry

Build Configuration

Environment Variables

First Deployment

Monitoring

​Troubleshooting

Overview

Deployment Workflow

Deployment Types

Manual Deployment

Automatic Deployment

Rebuild Deployment

Drop Deployment

Deployment States

Deployment History

Deployment Logs

Queue Management

Cancelling Deployments

Rollback Deployments

Enable Rollback

Perform Rollback

Multi-Server Deployments

Build Caching

Enable Cache

Clear Cache

Deployment Notifications

Best Practices

Build Configuration

Deployment Strategy

Security

Next Steps

Troubleshooting