Deploy Applications

Deploy Application

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

Endpoint

POST /application.deploy

Request Body

applicationId

string

required

ID of the application to deploy

title

string

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

description

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

applicationId

string

required

ID of the application to redeploy

title

string

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

description

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

applicationId

string

required

ID of the application with ongoing deployment

Response

success

boolean

Whether the cancellation request was successful

message

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

applicationId

string

required

ID of the application

owner

string

required

GitHub repository owner or organization

githubId

string

required

GitHub integration ID

enableSubmodules

boolean

required

Whether to clone Git submodules

repository

string

Repository name

branch

string

Branch to deploy from

buildPath

string

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

watchPaths

array

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

triggerType

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

applicationId

string

required

ID of the application

gitlabBranch

string

required

GitLab branch to deploy from

gitlabBuildPath

string

required

Build path within repository

gitlabOwner

string

required

GitLab owner/group

gitlabRepository

string

required

Repository name

gitlabId

string

required

GitLab integration ID

gitlabProjectId

number

required

GitLab project ID

gitlabPathNamespace

string

required

GitLab path namespace

enableSubmodules

boolean

required

Whether to clone Git submodules

watchPaths

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

applicationId

string

required

ID of the application

dockerImage

string

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

username

string

Registry username (for private registries)

password

string

Registry password (for private registries)

registryUrl

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

applicationId

string

required

ID of the application

enableSubmodules

boolean

required

Whether to clone Git submodules

customGitUrl

string

Git repository URL

customGitBranch

string

Branch to deploy from

customGitBuildPath

string

Build path within repository

customGitSSHKeyId

string

SSH key ID for authentication

watchPaths

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": "[email protected]: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

applicationId

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

applicationId

string

required

ID of the application

buildType

string

required

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

dockerContextPath

string

required

Docker build context path

dockerBuildStage

string

required

Docker build stage (for multi-stage builds)

dockerfile

string

Path to Dockerfile (for dockerfile build type)

publishDirectory

string

Directory to publish (for static sites)

isStaticSpa

boolean

Whether the static site is a Single Page Application

herokuVersion

string

Heroku buildpack version

railpackVersion

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

applicationId

string

required

ID of the application

createEnvFile

boolean

required

Whether to create an .env file from environment variables

env

string

Environment variables (newline-separated KEY=VALUE pairs)

buildArgs

string

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

buildSecrets

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

applicationId

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
}

Getting Started

Applications

Databases

Docker

Projects & Deployments

Monitoring

Administration