Deploy Application

Deploy, redeploy, and manage application deployments in Dokploy

Deploy Application

cURL

curl -X POST https://your-dokploy-instance.com/api/application.deploy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz",
    "title": "Deploy v2.0.0",
    "description": "Production deployment with new features"
  }'

200 Success

{
  "success": true
}

Triggers a new deployment of the application from its configured source. The deployment is queued and processed asynchronously.

Endpoint

POST /application.deploy

Request Body

applicationId · string · required

Unique identifier of the application to deploy.

Example: "cm5r8k9p00001xyz"

title · string

Optional title for this deployment. Appears in deployment logs and history.

Default: "Manual deployment"

Example: "Deploy v2.0.0"

description · string

Optional description providing context about this deployment.

Default: ""

Example: "Production deployment with new features"

Response

Returns true when the deployment is successfully queued. The actual deployment runs asynchronously.

Deployment Process

When you trigger a deployment:

1. Validation - Checks authorization and application configuration
2. Queue - Adds deployment job to the queue
3. Clone/Pull - Fetches code from configured source
4. Build - Builds application using configured build type
5. Push - Pushes built image to registry (if configured)
6. Deploy - Deploys container to target server
7. Health Check - Verifies application started successfully

---

Redeploy Application

cURL

curl -X POST https://your-dokploy-instance.com/api/application.redeploy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz",
    "title": "Rebuild deployment",
    "description": "Rebuilding to apply configuration changes"
  }'

200 Success

{
  "success": true
}

Rebuilds and redeploys the application using the same source code version. Useful for:

• Applying configuration changes
• Updating environment variables
• Rebuilding with updated base images
• Recovering from failed deployments

Endpoint

POST /application.redeploy

Request Body

applicationId · string · required

Unique identifier of the application to redeploy.

Example: "cm5r8k9p00001xyz"

title · string

Optional title for this redeployment.

Default: "Rebuild deployment"

Example: "Rebuild with new env vars"

description · string

Optional description for this redeployment.

Default: ""

Example: "Applying updated environment configuration"

Difference from Deploy

Feature	Deploy	Redeploy
Source	Latest from repository	Current deployed version
Use Case	New code changes	Configuration updates
Build Cache	Uses cache	Uses cache

---

Cancel Deployment

cURL

curl -X POST https://your-dokploy-instance.com/api/application.cancelDeployment \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz"
  }'

200 Success

{
  "success": true,
  "message": "Deployment cancellation requested"
}

Cancels an in-progress deployment. The application status is set to idle and the current deployment is marked as done.

Endpoint

POST /application.cancelDeployment

Request Body

applicationId · string · required

Unique identifier of the application whose deployment should be cancelled.

Example: "cm5r8k9p00001xyz"

Response Fields

success · boolean

Whether the cancellation request was successful.

message · string

Confirmation message about the cancellation.

Deployment cancellation is only available in cloud environments with remote servers. Self-hosted instances should use the killBuild endpoint instead.

---

Clean Deployment Queues

cURL

curl -X POST https://your-dokploy-instance.com/api/application.cleanQueues \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz"
  }'

200 Success

{}

Removes all pending deployment jobs for the application from the queue. Useful when deployments are stuck or you want to clear the queue.

Endpoint

POST /application.cleanQueues

Request Body

applicationId · string · required

Unique identifier of the application whose queues should be cleaned.

---

Kill Build Process

cURL

curl -X POST https://your-dokploy-instance.com/api/application.killBuild \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz"
  }'

200 Success

{}

Kills the Docker build process for the application. Use this to forcefully stop a stuck build.

Endpoint

POST /application.killBuild

Request Body

applicationId · string · required

Unique identifier of the application whose build should be killed.

This forcefully terminates the build process. The application status will be set to error. You’ll need to trigger a new deployment to recover.

---

Clear Old Deployments

cURL

curl -X POST https://your-dokploy-instance.com/api/application.clearDeployments \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz"
  }'

200 Success

{
  "success": true
}

Clears old deployment artifacts and logs for the application. This helps free up disk space.

Endpoint

POST /application.clearDeployments

Request Body

applicationId · string · required

Unique identifier of the application whose old deployments should be cleared.

Deployment Best Practices

Use descriptive titles and descriptions for deployments. This makes it easier to track what was deployed and when in your deployment history.

Monitor application status after triggering a deployment:

• running - Deployment in progress
• done - Deployment completed successfully
• error - Deployment failed

Avoid triggering multiple deployments simultaneously. Wait for the current deployment to complete before starting a new one.

Example: Deployment Workflow

Complete Workflow

# 1. Check current status
curl https://your-dokploy-instance.com/api/application.one?applicationId=cm5r8k9p00001xyz \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# 2. Update environment variables
curl -X POST https://your-dokploy-instance.com/api/application.saveEnvironment \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz",
    "env": "NODE_ENV=production\nAPI_KEY=new-key",
    "createEnvFile": true
  }'

# 3. Deploy the application
curl -X POST https://your-dokploy-instance.com/api/application.deploy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz",
    "title": "Deploy with updated API key",
    "description": "Updated API credentials"
  }'

# 4. Monitor status (poll this endpoint)
curl https://your-dokploy-instance.com/api/application.one?applicationId=cm5r8k9p00001xyz \
  -H "Authorization: Bearer YOUR_API_TOKEN"