Dokploy

Dokploy Infrastructure Management

Dokploy is a self-hosted PaaS. All management happens through its REST API using curl. No CLI tools or bash scripts — construct curl commands directly.

Authentication & Request Pattern

Environment variables (must be set):

• DOKPLOY_API_URL — base URL of the Dokploy instance (e.g., https://dokploy.example.com)
• DOKPLOY_API_KEY — API token generated from Dokploy UI: Settings → Profile → API/CLI Section

All endpoints follow the pattern: $DOKPLOY_API_URL/api/{router}.{procedure}

GET request (reads)

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/{endpoint}?{param}={value}"

Parameters are flat query params. Do NOT use tRPC ?input= encoding — it doesn't work on the OpenAPI surface.

POST request (all mutations)

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/{endpoint}" \
  -d '{"param": "value"}'

Every mutation (create, update, remove, deploy, start, stop, reload) uses POST. Never use PUT, PATCH, or DELETE.

Always pipe output through jq for readability: | jq .

Response Formats

Not all endpoints return JSON objects. Be aware of these patterns:

• application.update, application.saveEnvironment, and other mutation endpoints may return a bare true instead of the updated object. Do not pipe these through jq with object filters — use jq . or skip jq entirely.
• application.deploy returns empty output on success.
• GET endpoints (*.one, *.all) return full JSON objects.
• When in doubt, don't assume the response shape — capture raw output first.

Critical: The Resource Hierarchy

Project
  └── Environment (default: "production")
        ├── Applications
        ├── Databases (postgres, mysql, mariadb, mongo, redis)
        └── Compose services

• Every project has at least one environment. The default is named "production" with isDefault: true.
• Creating any resource requires environmentId, NOT projectId.
• To get environmentId: fetch the project with project.one, then read .environments[0].environmentId (or find the environment by name).

This is the most common source of errors. Always fetch the environment first.

Quick Reference

Projects & Environments

Applications

Databases

All database types share the same operation pattern. Replace {type} with: postgres, mysql, mariadb, mongo, redis.

Note: Each type uses its own ID field name: postgresId, mysqlId, mariadbId, mongoId, redisId.

Domains

Compose

Deployments

type values: application, compose, server, schedule, previewDeployment, backup, volumeBackup

Servers

Common Workflows

List all projects with their resources

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.all" | jq .

The response includes nested environments with all applications, databases, and compose services summarized.

Deploy an existing application

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.deploy" \
  -d '{"applicationId": "THE_APP_ID"}' | jq .

Create a new app in an existing project

Step 1 — Get the project's environmentId:

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.one?projectId=PROJECT_ID" \
  | jq '.environments[] | select(.isDefault) | .environmentId'

Step 2 — Create the application:

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.create" \
  -d '{"name": "my-app", "environmentId": "ENV_ID"}' | jq .

Create a full project from scratch

Step 1 — Create the project:

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/project.create" \
  -d '{"name": "My Project", "description": "Project description"}' | jq .

Step 2 — Get the new project's environmentId from the response, or fetch it:

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.all" \
  | jq '.[] | select(.name == "My Project") | .environments[0].environmentId'

Step 3 — Create resources using that environmentId (apps, databases, compose).

Check deployment status

For applications:

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/deployment.all?applicationId=APP_ID" | jq '.[0]'

For compose services:

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/deployment.allByType?id=COMPOSE_ID&type=compose" | jq '.[0]'

Set environment variables on an app

Env vars are set as a single newline-separated string block, not key-value pairs.

Required fields: buildArgs, buildSecrets, and createEnvFile are mandatory (use empty strings and false as defaults):

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.saveEnvironment" \
  -d '{
    "applicationId": "APP_ID",
    "env": "DATABASE_URL=postgres://...\nREDIS_URL=redis://...\nNODE_ENV=production",
    "buildArgs": "",
    "buildSecrets": "",
    "createEnvFile": false
  }'

Important Notes

• project.all returns a comprehensive overview — use it to discover IDs before drilling down.
• Deployment is asynchronous. After triggering deploy, poll deployment.all or deployment.allByType to check status.
• Destructive operations (remove, delete) cannot be undone. Always confirm with the user first.
• The Swagger UI is available at $DOKPLOY_API_URL/swagger for interactive API exploration (admin only).

Reference Files

For full endpoint details with all parameters: