dokploy-deploy
Dokploy Deployment
Deploy and manage applications on a self-hosted Dokploy instance. Dokploy is an open-source PaaS (alternative to Vercel/Heroku) using Docker + Traefik.
Quick Reference
| Item | Value |
|---|---|
| Dashboard | https://<DOKPLOY_HOST>/ |
| API base | https://<DOKPLOY_HOST>/api/ |
| Swagger UI | https://<DOKPLOY_HOST>/swagger (browser login required) |
| Auth header | x-api-key: <TOKEN> |
| CLI install | npm install -g @dokploy/cli |
| MCP server | @ahdev/dokploy-mcp (67 tools) |
| Docs | https://docs.dokploy.com |
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 ~/.claude/skills/dokploy-deploy/scripts/setup.py
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 ~/.claude/skills/dokploy-deploy/scripts/setup.py --url https://dokploy.example.com --key YOUR_API_KEY
After setup, the MCP server (@ahdev/dokploy-mcp, 67 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.
| Endpoint | Method | Purpose |
|---|---|---|
project.all |
GET | List all projects |
project.one |
GET | Get project by ID |
application.one |
GET | Get app details + status |
application.deploy |
POST | Trigger deployment |
application.stop |
POST | Stop application |
application.start |
POST | Start application |
application.update |
POST | Update app settings |
application.saveBuildType |
POST | Change build type |
application.saveEnvironment |
POST | Set environment variables |
deployment.all |
GET | List deployments for app |
domain.byApplicationId |
GET | Get domains for app |
domain.create |
POST | Add custom domain |
postgres.one |
GET | Get PostgreSQL service |
postgres.update |
POST | Update PostgreSQL settings |
redis.one |
GET | Get Redis service |
docker.getContainersByAppNameMatch |
GET | List Docker containers |
application.readTraefikConfig |
GET | Read Traefik config |
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 (67 tools — preferred for AI agents)
When MCP is available, prefer MCP tools over curl. MCP handles tRPC URL encoding and response parsing automatically.
See references/MCP-TOOLS.md for the full 67-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", "@ahdev/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.
Key MCP Tools by Category
Projects: project-all, project-one, project-create, project-update, project-duplicate, project-remove
Applications (26 tools):
- Status:
application-one,application-create,application-update,application-delete,application-move - Deploy:
application-deploy,application-redeploy,application-start,application-stop,application-cancelDeployment,application-reload - Config:
application-saveBuildType,application-saveEnvironment - Git:
application-saveGithubProvider,application-saveGitlabProvider,application-saveBitbucketProvider,application-saveGiteaProvider,application-saveGitProvider,application-saveDockerProvider,application-disconnectGitProvider - Monitoring:
application-readAppMonitoring,application-readTraefikConfig,application-updateTraefikConfig
Domains (9 tools): domain-byApplicationId, domain-create, domain-update, domain-delete, domain-validateDomain, domain-generateDomain
PostgreSQL (13 tools): postgres-create, postgres-one, postgres-update, postgres-remove, postgres-deploy, postgres-start, postgres-stop, postgres-rebuild, postgres-saveExternalPort, postgres-saveEnvironment
MySQL (13 tools): Same pattern with mysql-* prefix.
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 curl or Dashboard)
- Build/container logs — WebSocket only, no MCP tool
- Redis management — not in MCP, use
redis.*API via curl - MariaDB/MongoDB — not in MCP, use
mariadb.*/mongo.*API - Docker Compose — not in MCP, use
compose.*API - Backups, notifications, schedules — not in MCP
Common Pitfalls
See references/PITFALLS.md for detailed solutions.
| Problem | Cause | Fix |
|---|---|---|
COPY /app/public fails |
Git ignores empty dirs | RUN mkdir -p public in Dockerfile |
| DB connection error | Neon HTTP driver vs standard PG | Use postgres (postgres.js) package |
Clerk publishableKey missing |
SSG validates env at build | export const dynamic = "force-dynamic" + skip provider in build phase |
| Container crash with migrate.mjs | standalone output lacks modules | Run migrations via in-app API endpoint |
| Build logs unavailable via API | WebSocket only, no REST | Check Dashboard UI or poll deployment.all for status |
| Container logs unavailable via API | WebSocket only | Use Dashboard UI |
| External DB port unreachable | VPS firewall blocks port | Use internal Docker network names |
| SSL certificate error from curl | Self-signed or Let's Encrypt delay | Use curl -sk or wait for cert provisioning |
| 404 on API routes after deploy | Route not in standalone output | Verify route exists in .next/standalone |
Build Types
Dokploy supports:
| Type | When to use |
|---|---|
| Dockerfile | Custom builds, multi-stage, full control |
| Nixpacks | Auto-detect language, zero config |
| Buildpack | Heroku/Paketo compatible apps |
| Docker Image | Pre-built images from registry |
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
- Add domain via Dashboard or API (
domain.create) - Point DNS A-record to VPS IP
- Dokploy auto-provisions Let's Encrypt certificate via Traefik
- HTTPS works automatically after DNS propagation
Next.js Specific Guide
See references/NEXTJS-GUIDE.md for full details on deploying Next.js to Dokploy.