Dokploy Deployment

Deploy and manage applications on a self-hosted Dokploy instance (v0.28.4+). Dokploy is an open-source PaaS (alternative to Vercel/Heroku) using Docker + Traefik v3.

Quick Reference

First Run — Setup

On first use, check if the Dokploy MCP server is configured. If not, run the interactive setup:

1. Check: does ~/.claude/mcp.json contain a "dokploy" server entry?
2. If NO → run: python3 skills/dokploy-api-mcp/scripts/setup.py
   (or the full path in the user's skill installation directory)
3. The script will:
   - Ask for Dokploy URL (e.g., https://dokploy.example.com)
   - Ask for API key (generated in Dashboard → Settings → Profile → API/CLI)
   - Validate the connection
   - Auto-configure ~/.claude/mcp.json with the MCP server
4. Tell the user: "Restart Claude Code to activate the Dokploy MCP server."

With CLI arguments (non-interactive):

python3 skills/dokploy-api-mcp/scripts/setup.py --url https://dokploy.example.com --key YOUR_API_KEY

After setup, the MCP server (@sattva/dokploy-mcp, 449 tools) will be available on next Claude Code restart. Prefer MCP tools over curl for all operations.

Environment Variables

Before using this skill, ensure these are available:

DOKPLOY_URL=https://dokploy.example.com
DOKPLOY_API_KEY=<generated-api-token>

Generate API token: Dashboard → Settings → Profile → API/CLI → Generate.

Deployment Workflow

Step 1: Check Current State

# Get application status
curl -s -X GET "${DOKPLOY_URL}/api/trpc/application.one?input=$(python3 -c "
import urllib.parse, json
print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}})))
")" -H "x-api-key: ${DOKPLOY_API_KEY}"

Step 2: Trigger Deploy

# Deploy application (POST — mutation)
curl -s -X POST "${DOKPLOY_URL}/api/application.deploy" \
  -H "x-api-key: ${DOKPLOY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"json":{"applicationId":"APP_ID"}}'

Step 3: Monitor Deploy Status

# Poll deployment status
curl -s -X GET "${DOKPLOY_URL}/api/trpc/deployment.all?input=$(python3 -c "
import urllib.parse, json
print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}})))
")" -H "x-api-key: ${DOKPLOY_API_KEY}"

Step 4: Verify Health

curl -sk "https://<app-domain>/api/health"

API Reference

Dokploy uses tRPC internally. Two request formats:

Queries (read) — GET with encoded input

GET /api/trpc/<router>.<procedure>?input=URL_ENCODED({"json":{...}})
Header: x-api-key: <token>

Mutations (write) — POST with JSON body

POST /api/<router>.<procedure>
Header: x-api-key: <token>
Header: Content-Type: application/json
Body: {"json":{...}}

Key Endpoints

See references/API-REFERENCE.md for the full list (449 endpoints).

CLI Usage

# Install
npm install -g @dokploy/cli

# Authenticate (creates ~/.config/dokploy/config.json)
dokploy authenticate

# Verify token
dokploy verify

# Application management
dokploy app create   # Create new application
dokploy app deploy   # Deploy application
dokploy app stop     # Stop application
dokploy app delete   # Delete application

# Database management
dokploy db create    # Create database service
dokploy db delete    # Delete database service

# Environment variables
dokploy env set      # Set env vars
dokploy env list     # List env vars

# Project management
dokploy project create
dokploy project list

MCP Server (449 tools — full API coverage)

When MCP is available, ALWAYS prefer MCP tools over curl. MCP handles tRPC URL encoding and response parsing automatically.

See references/MCP-TOOLS.md for the full 449-tool reference.

Setup

Automatic (recommended): Run the setup script from the "First Run" section above — it configures MCP automatically.

Manual (~/.claude/mcp.json):

{
  "mcpServers": {
    "dokploy": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@sattva/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com/api",
        "DOKPLOY_API_KEY": "<your-api-token>"
      }
    }
  }
}

Note: On macOS/Linux use "command": "npx" directly instead of cmd /c. Local dev: use "command": "node", "args": ["e:/My/MCP/dokploy-mcp/dist/index.js"].

MCP Tools by Category (449 total)

MCP Deployment Workflow

1. application_one                → check current status
2. application_saveEnvironment    → set/update env vars if needed
3. application_saveBuildType      → ensure Dockerfile build configured
4. application_deploy             → trigger deployment
5. application_one                → poll until applicationStatus = "done"
6. curl health endpoint           → verify app is working

MCP Limitations (use Dashboard only)

• Build/container logs — WebSocket only, no MCP or REST endpoint
• Docker exec into container — No API endpoint, use SSH to VPS

Everything else is available through MCP tools, including: Redis, MariaDB, MongoDB, Compose, Backups, Notifications, Schedules, Rollbacks, SSO, Patches, Organizations, and more.

Common Pitfalls

See references/PITFALLS.md for detailed solutions.

Build Types

Dokploy supports:

Services (Databases)

Create via Dashboard → Project → Add Service:

• PostgreSQL — internal hostname: <appName>:5432
• MySQL/MariaDB — internal hostname: <appName>:3306
• MongoDB — internal hostname: <appName>:27017
• Redis — internal hostname: <appName>:6379

Internal hostnames use Docker network. External ports optional (may need firewall rules).

Domain & SSL

1. Add domain via Dashboard or API (domain.create)
2. Point DNS A-record to VPS IP
3. Dokploy auto-provisions Let's Encrypt certificate via Traefik v3
4. HTTPS works automatically after DNS propagation

Next.js Specific Guide

See references/NEXTJS-GUIDE.md for full details on deploying Next.js 14/15 to Dokploy.