Deploy Applications

Deploy Application

Trigger a new deployment of an application from the configured source.

Endpoint

POST /application.deploy

Request Body

string

required

ID of the application to deploy

string

Title for the deployment log (default: “Manual deployment”)

string

Description for the deployment log

Response

Returns success status. The deployment runs asynchronously in the background.

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.deploy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "title": "Deploy version 2.1.0",
    "description": "Deploying new features and bug fixes"
  }'

Example Response

{
  "success": true
}

Redeploy Application

Redeploy an application, optionally clearing the build cache.

Endpoint

POST /application.redeploy

Request Body

string

required

ID of the application to redeploy

string

Title for the deployment log (default: “Rebuild deployment”)

string

Description for the deployment log

Response

Returns success status. The redeployment runs asynchronously.

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.redeploy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "title": "Rebuild with clean cache",
    "description": "Rebuilding to resolve build issues"
  }'

Example Response

{
  "success": true
}

Cancel Deployment

Cancel an ongoing deployment (cloud version only).

Endpoint

POST /application.cancelDeployment

Request Body

string

required

ID of the application with ongoing deployment

Response

boolean

Whether the cancellation request was successful

string

Status message

Example Request

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

Example Response

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

Configure Git Providers

Save GitHub Provider

Configure GitHub as the application source.

Endpoint

POST /application.saveGithubProvider

Request Body

string

required

ID of the application

string

required

GitHub repository owner or organization

string

required

GitHub integration ID

boolean

required

Whether to clone Git submodules

string

Repository name

string

Branch to deploy from

string

Path within repository to build from (default: ”/”)

array

Array of paths to watch for changes (for monorepo support)

string

default:"push"

Deployment trigger: push or tag

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.saveGithubProvider \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "owner": "my-org",
    "repository": "my-repo",
    "branch": "main",
    "buildPath": "/apps/frontend",
    "githubId": "gh_abc123",
    "watchPaths": ["apps/frontend/**"],
    "enableSubmodules": false,
    "triggerType": "push"
  }'

Save GitLab Provider

Configure GitLab as the application source.

Endpoint

POST /application.saveGitlabProvider

Request Body

string

required

ID of the application

string

required

GitLab branch to deploy from

string

required

Build path within repository

string

required

GitLab owner/group

string

required

Repository name

string

required

GitLab integration ID

number

required

GitLab project ID

string

required

GitLab path namespace

boolean

required

Whether to clone Git submodules

array

Array of paths to watch for changes

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.saveGitlabProvider \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "gitlabOwner": "my-group",
    "gitlabRepository": "my-project",
    "gitlabBranch": "main",
    "gitlabBuildPath": "/",
    "gitlabId": "gl_xyz789",
    "gitlabProjectId": 12345,
    "gitlabPathNamespace": "my-group/my-project",
    "enableSubmodules": false
  }'

Save Docker Provider

Configure Docker registry as the application source.

Endpoint

POST /application.saveDockerProvider

Request Body

string

required

ID of the application

string

Docker image name (e.g., “nginx:latest”)

string

Registry username (for private registries)

string

Registry password (for private registries)

string

Custom registry URL (default: Docker Hub)

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.saveDockerProvider \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "dockerImage": "myorg/myapp:v2.1.0",
    "username": "myuser",
    "password": "mypassword",
    "registryUrl": "https://registry.example.com"
  }'

Save Custom Git Provider

Configure a custom Git repository via SSH or HTTPS.

Endpoint

POST /application.saveGitProvider

Request Body

string

required

ID of the application

boolean

required

Whether to clone Git submodules

string

Git repository URL

string

Branch to deploy from

string

Build path within repository

string

SSH key ID for authentication

array

Array of paths to watch for changes

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.saveGitProvider \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "customGitUrl": "git@git.example.com:org/repo.git",
    "customGitBranch": "production",
    "customGitBuildPath": "/",
    "customGitSSHKeyId": "key_abc123",
    "enableSubmodules": true
  }'

Disconnect Git Provider

Disconnect the configured Git provider from an application.

Endpoint

POST /application.disconnectGitProvider

Request Body

string

required

ID of the application

Example Request

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

Configure Build Settings

Save Build Type

Configure the build system and related settings for an application.

Endpoint

POST /application.saveBuildType

Request Body

string

required

ID of the application

string

required

Build system: dockerfile, nixpacks, heroku_buildpacks, paketo_buildpacks, railpack, or static

string

required

Docker build context path

string

required

Docker build stage (for multi-stage builds)

string

Path to Dockerfile (for dockerfile build type)

string

Directory to publish (for static sites)

boolean

Whether the static site is a Single Page Application

string

Heroku buildpack version

string

Railpack version

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.saveBuildType \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "buildType": "dockerfile",
    "dockerfile": "./Dockerfile",
    "dockerContextPath": "./",
    "dockerBuildStage": "production"
  }'

Save Environment Variables

Configure environment variables, build arguments, and build secrets.

Endpoint

POST /application.saveEnvironment

Request Body

string

required

ID of the application

boolean

required

Whether to create an .env file from environment variables

string

Environment variables (newline-separated KEY=VALUE pairs)

string

Build-time arguments (newline-separated KEY=VALUE pairs)

string

Build-time secrets (newline-separated KEY=VALUE pairs)

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.saveEnvironment \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "env": "NODE_ENV=production\nPORT=3000\nDATABASE_URL=postgresql://...",
    "buildArgs": "NODE_VERSION=18\nYARN_VERSION=1.22.19",
    "buildSecrets": "NPM_TOKEN=secret_token",
    "createEnvFile": true
  }'

Clear Deployments

Remove old deployment records and artifacts to free up disk space.

Endpoint

POST /application.clearDeployments

Request Body

string

required

ID of the application

Example Request

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

Example Response

{
  "success": true
}