From watzon-claude-code
Use when deploying, managing, or troubleshooting Dokploy instances via the CLI (https://github.com/Dokploy/cli). Triggers: "dokploy deploy", "manage dokploy", "dokploy app", "dokploy database", "push to dokploy", "dokploy CI/CD", "dokploy authentication", "zero-downtime deployment", "dokploy docker-compose", "dokploy environment variables", "dokploy health checks". Provides comprehensive workflows for authentication, project/app/database management, environment variable sync, and production-ready CI/CD patterns with GitHub Actions.
npx claudepluginhub joshuarweaver/cascade-code-languages-misc-2 --plugin watzon-claude-codeThis skill uses the workspace's default tool permissions.
Comprehensive guide for managing Dokploy instances via CLI, API, and production deployment patterns.
README.mdassets/docker-compose.template.ymlassets/github-actions.template.ymlcli/README.mdcli/commands/app.tscli/commands/auth.tscli/commands/compose.tscli/commands/database.tscli/commands/docker.tscli/commands/domain.tscli/commands/project.tscli/commands/server.tscli/deno.jsoncli/deno.lockcli/lib/client.tscli/lib/config.tscli/lib/output.tscli/mod.tsreferences/advanced-workflows.mdreferences/api-reference.mdCreates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Comprehensive guide for managing Dokploy instances via CLI, API, and production deployment patterns.
This skill includes two CLI options:
| CLI | Coverage | Runtime | Best For |
|---|---|---|---|
Custom CLI (./cli/) | ~90% of API | Deno (single binary) | Full control, CI/CD, automation |
Official CLI (@dokploy/cli) | ~8% of API | Node.js 18+ | Basic operations |
Recommendation: Use the custom CLI for comprehensive API access and zero-dependency deployment.
| Task | Command | Notes |
|---|---|---|
| Authenticate | dokploy auth login --url <url> --token <token> | Saves to ~/.config/dokploy/ |
| Deploy app | dokploy app deploy <appId> | No interactive prompts |
| Create compose | dokploy compose create --name <n> --environment <id> | Full compose support |
| Manage domains | dokploy domain create --host <h> --app <id> | SSL, paths, ports |
| Database ops | dokploy db create postgres --name <n> --environment <id> | All 5 DB types |
| CI/CD | DOKPLOY_TOKEN=x dokploy app deploy <id> | Env var auth |
# Option 1: Run with Deno
deno run --allow-all ./cli/mod.ts [command]
# Option 2: Compile to binary
cd cli && deno task compile
./dist/dokploy --help
# Option 3: Install globally
deno install --allow-all -n dokploy ./cli/mod.ts
npm install -g @dokploy/cli
# Interactive
dokploy auth login --url https://panel.example.com --token YOUR_TOKEN
# Environment variables (CI/CD)
export DOKPLOY_URL="https://panel.example.com"
export DOKPLOY_TOKEN="YOUR_TOKEN"
# Check status
dokploy auth status
~/.config/dokploy/config.json:
{
"url": "https://panel.example.com",
"token": "your-token",
"defaultProjectId": "optional",
"defaultEnvironmentId": "optional"
}
# 1. Authenticate
dokploy auth login --url https://panel.example.com --token TOKEN
# 2. Create project
dokploy project create --name "Production"
# 3. Get project details (includes environment IDs)
dokploy project get <projectId>
# 4. Create application
dokploy app create --name "web-app" --environment <envId>
# 5. Set environment variables
dokploy app env <appId> --file .env.production
# 6. Deploy
dokploy app deploy <appId>
# Create compose stack (defaults to sourceType=github, must change to raw)
dokploy compose create \
--name "full-stack" \
--environment <envId> \
--file docker-compose.yml
# IMPORTANT: Set source type to "raw" for direct compose files
# (Use API client or Deno script - see "Compose Source Types" section below)
# Set environment variables for the compose stack
# (Use API client - env vars go in compose.update with "env" field)
# Deploy
dokploy compose deploy <composeId>
# Add domain (pointing to specific service)
dokploy domain create \
--host app.example.com \
--compose <composeId> \
--service web \
--https \
--port 80
# IMPORTANT: Redeploy after adding domain for Traefik to pick up the route
dokploy compose deploy <composeId>
# Create PostgreSQL
dokploy db create postgres \
--name "Production DB" \
--environment <envId> \
--db-name myapp \
--db-user postgres \
--db-password "$DB_PASSWORD"
# Deploy
dokploy db deploy postgres <postgresId>
# Supported: postgres, mysql, mariadb, mongo, redis
# Create HTTPS domain with Let's Encrypt
dokploy domain create \
--host api.example.com \
--app <appId> \
--https \
--cert letsencrypt
# Generate traefik.me domain (for testing)
dokploy domain generate --app-name myapp
name: Deploy to Dokploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Deno
uses: denoland/setup-deno@v2
- name: Deploy
env:
DOKPLOY_URL: ${{ secrets.DOKPLOY_URL }}
DOKPLOY_TOKEN: ${{ secrets.DOKPLOY_TOKEN }}
run: |
deno run --allow-all ./cli/mod.ts app deploy ${{ secrets.APP_ID }}
Or with direct API call:
- name: Deploy to Dokploy
run: |
curl -X POST "${{ secrets.DOKPLOY_URL }}/api/application.deploy" \
-H "x-api-key: ${{ secrets.DOKPLOY_TOKEN }}" \
-H "Content-Type: application/json" \
-d '{"applicationId": "${{ secrets.APP_ID }}"}'
dokploy auth login --url <url> --token <token>
dokploy auth logout
dokploy auth status
dokploy auth set-default --project <id> --environment <id>
dokploy project list
dokploy project get <projectId>
dokploy project create --name <name> [--description <desc>]
dokploy project delete <projectId> [--force]
dokploy app get <appId>
dokploy app create --name <name> --environment <envId> [--app-name <slug>]
dokploy app deploy <appId> [--title <title>]
dokploy app redeploy <appId>
dokploy app start <appId>
dokploy app stop <appId>
dokploy app delete <appId> [--force]
dokploy app env <appId> # Get env vars
dokploy app env <appId> --set KEY=value # Set env var
dokploy app env <appId> --file .env # Set from file
dokploy compose get <composeId>
dokploy compose create --name <name> --environment <envId> [--file <path>] [--type docker-compose|stack]
dokploy compose deploy <composeId>
dokploy compose start <composeId>
dokploy compose stop <composeId>
dokploy compose delete <composeId> [--force]
dokploy compose file <composeId> # Get compose file
dokploy compose file <composeId> --set <path> # Update compose file
dokploy domain list --app <appId>
dokploy domain list --compose <composeId>
dokploy domain get <domainId>
dokploy domain create --host <host> --app <appId> [--https] [--port <port>] [--path <path>]
dokploy domain create --host <host> --compose <composeId> --service <name>
dokploy domain delete <domainId> [--force]
dokploy domain generate --app-name <name>
# Supported types: postgres, mysql, mariadb, mongo, redis
dokploy db create <type> --name <name> --environment <envId> \
[--db-name <name>] [--db-user <user>] [--db-password <pass>] [--image <image>]
dokploy db deploy <type> <databaseId>
dokploy db start <type> <databaseId>
dokploy db stop <type> <databaseId>
dokploy db delete <type> <databaseId> [--force]
dokploy server list
dokploy server get <serverId>
dokploy server create --name <name> --ip <ip> --port <port> --user <user> --ssh-key <keyId> --type deploy|build
dokploy server validate <serverId>
dokploy server delete <serverId> [--force]
dokploy docker containers [--server <serverId>]
dokploy docker restart <containerId> [--server <serverId>]
All commands support --json for machine-readable output:
dokploy project list --json | jq '.[].projectId'
dokploy app get abc123 --json > app-config.json
The custom CLI uses these API endpoints:
| Category | Endpoints | Coverage |
|---|---|---|
| Auth | user.get | ✅ |
| Projects | project.all, project.one, project.create, project.remove | ✅ |
| Applications | application.* (27 endpoints) | ✅ |
| Compose | compose.* (26 endpoints) | ✅ |
| Domains | domain.* (9 endpoints) | ✅ |
| Databases | postgres.*, mysql.*, mariadb.*, mongo.*, redis.* | ✅ |
| Servers | server.* (16 endpoints) | ✅ |
| Docker | docker.* (7 endpoints) | ✅ |
See ./cli/lib/client.ts for the full typed API client.
When creating a compose stack, the default sourceType is github. For raw compose files (no git repo), you must update to sourceType: "raw":
// Using the API client directly (Deno)
import { DokployClient } from "./cli/lib/client.ts";
const client = await DokployClient.create();
// Update source type to raw
await client.updateCompose("<composeId>", { sourceType: "raw" });
// Set environment variables
await client.updateCompose("<composeId>", {
env: `VAR1=value1
VAR2=value2`
});
Without this, deployment will fail with "Github Provider not found".
Dokploy does NOT support env_file directive in docker-compose.yml. You must:
environment section&anchor / *anchor) for shared env varsenv field)Before (won't work):
services:
app:
env_file:
- .env
After (works):
services:
app:
environment:
DB_HOST: "${DB_HOST}"
DB_PASS: "${DB_PASS}"
After adding a domain to an application or compose stack, you must redeploy for Traefik to pick up the new routing:
dokploy domain create --host example.com --compose <id> --service web --https
dokploy compose deploy <id> # Required!
All services must be on dokploy-network (external) to be routable:
services:
web:
networks:
- dokploy-network
networks:
dokploy-network:
external: true
# Check current auth
dokploy auth status
# Re-authenticate
dokploy auth login --url https://... --token ...
# Verify environment variables are set
env | grep DOKPLOY
dokploy compose get <id> or dokploy app get <id>sourceType: "raw" for direct compose filesdokploy-network and redeploy after adding domaindokploy-network exists: docker network lsRun list commands to find IDs:
dokploy project list --json | jq '.[] | {id: .projectId, name: .name}'
dokploy project get <projectId> --json | jq '.environments[] | {id: .environmentId, name: .name}'
./cli/ directory in this skillhttps://your-instance/api/settings.getOpenApiDocumentComplete example deploying a multi-service app with database:
# 1. Create the compose stack
dokploy compose create --name "MyApp" --environment <envId> --file docker-compose.yml
# 2. Set source type to raw (required for direct compose files)
deno run --allow-all - <<'EOF'
import { DokployClient } from "./cli/lib/client.ts";
const client = await DokployClient.create();
await client.updateCompose("<composeId>", {
sourceType: "raw",
env: `DB_PASSWORD=secretpass123
REDIS_URL=redis://redis:6379`
});
console.log("Updated!");
EOF
# 3. Deploy
dokploy compose deploy <composeId>
# 4. Verify containers are running
dokploy docker containers | grep <app-name>
# 5. Add domain
dokploy domain create --host myapp.example.com --compose <composeId> --service web --https --port 80
# 6. Redeploy to apply domain routing
dokploy compose deploy <composeId>
# 7. Verify
curl https://myapp.example.com/health