juanjosegongi/dokploy

Dokploy Operations

Use this skill to manage Dokploy with a CLI-first workflow and an API fallback when commands are unavailable or insufficient.

Skill Contents

• SKILL.md: Routing, safety rules, and end-to-end workflows.
• references/cli.md: Command map and non-interactive command examples.
• references/api.md: Endpoint map and curl examples for OpenAPI and tRPC styles.
• scripts/dokploy_api.py: Safer API helper with retries, dry-run mode, and endpoint-style fallback.
• scripts/stop_app.sh: Wrapper for application.stop incident action.
• scripts/rollback.sh: Wrapper for rollback.rollback incident action.
• scripts/kill_deployment.sh: Wrapper for deployment.killProcess incident action.
• references/operator-playbook.md: Incident workflow for stop, rollback, and stuck-deployment recovery.

When to Use

Use this skill when users ask to:

• Deploy to Dokploy.
• Create or manage Dokploy projects, environments, applications, or databases.
• Pull or push environment variables for Dokploy services.
• Trigger deployments, stop services, or remove resources.
• Operate Dokploy via API instead of the CLI.

Preconditions

Before performing any mutation, verify all of the following:

1. Dokploy base URL is known, for example https://dokploy.example.com.
2. API key/token is available from Dokploy profile settings.
3. The target project/environment/resource is identified by ID, not only by name.
4. A non-destructive list/read command has been run first.

Never print secrets in logs or commit them to files.

Execution Routing

1. Prefer CLI when dokploy is installed and command coverage is sufficient.
2. Use API when:
   • CLI is not installed.
   • The action is not exposed in CLI.
   • Bulk automation or scriptable JSON output is needed.
3. If an API request fails due to endpoint style mismatch, switch between:
   • OpenAPI style: /api/<resource>.<action>
   • tRPC style: /api/trpc/<resource>.<action>

See references/api.md for payload differences.

Safer API Helper

Use the bundled helper for API calls that need:

• Automatic style fallback (openapi then trpc, or the reverse).
• Retries for transient failures.
• Dry-run preview before execution.
• Destructive-action guardrails (--yes required).

Examples:

• Read call:
  • python3 skills/dokploy/scripts/dokploy_api.py project.all --style auto
• Mutating call (requires confirmation flag):
  • python3 skills/dokploy/scripts/dokploy_api.py application.stop --method POST --json '{"applicationId":"<applicationId>"}' --yes
• Dry run first:
  • python3 skills/dokploy/scripts/dokploy_api.py application.stop --method POST --json '{"applicationId":"<applicationId>"}' --dry-run

Standard Workflow

1) Connectivity and Auth

• CLI path:
  • Install: npm install -g @dokploy/cli
  • Authenticate: dokploy authenticate --url "$DOKPLOY_URL" --token "$DOKPLOY_AUTH_TOKEN"
  • Verify: dokploy verify
• API path:
  • Smoke test: curl -sS "$DOKPLOY_URL/api/project.all" -H "x-api-key: $DOKPLOY_AUTH_TOKEN"

2) Inventory First

• List projects, then inspect target project.
• Resolve environment IDs before app or database actions.
• Resolve application/database IDs before deploy/stop/delete actions.

3) Execute the Requested Change

• For project, environment, app, and database CRUD/deploy operations, prefer CLI.
• For advanced operations (deployment process control, container introspection, server-level actions), use API when needed.

4) Verify Outcome

• Re-read the mutated resource.
• Check deployment status where relevant.
• Confirm resulting state matches the user request.

High-Value Workflows

Deploy an application

1. Resolve projectId, environmentId, and applicationId.
2. Trigger deploy via CLI: dokploy app deploy --applicationId <id> --skipConfirm
3. Fallback API: POST /api/application.deploy with applicationId.
4. Verify by querying deployment/application status.

Create full app path

1. Create project.
2. Create environment within project.
3. Create application within environment.
4. Configure source/build settings if needed.
5. Deploy and verify.

Manage database lifecycle

1. Create the database service in the target environment.
2. Deploy/start/stop based on requested state.
3. Save env changes only through secure channels.
4. Verify with resource fetch after each mutation.

Handle incidents (stop, rollback, kill)

Use references/operator-playbook.md for response-ready workflows:

1. Stop impacted application or database service.
2. Kill stuck deployment process when queues are blocked.
3. Execute rollback using a verified rollbackId.
4. Re-verify state and service health.

Quick wrappers for common incident commands:

• Stop app: bash skills/dokploy/scripts/stop_app.sh <applicationId> --dry-run then --yes
• Rollback: bash skills/dokploy/scripts/rollback.sh <rollbackId> --dry-run then --yes
• Kill stuck deployment: bash skills/dokploy/scripts/kill_deployment.sh <deploymentId> --dry-run then --yes

Synchronize environment variables

1. Pull to local file first.
2. Review intended diff.
3. Push with explicit confirmation.
4. Redeploy service if required by runtime behavior.

Safety Rules

• Always run a read/list operation before destructive commands.
• Confirm delete operations explicitly unless user requested forceful automation.
• Avoid storing API keys in tracked files.
• Do not expose credentials in responses, logs, screenshots, or command history snippets.
• For production targets, favor staged rollout and post-change verification.

Common Pitfalls

• Command naming drifts across versions. Run dokploy --help and scoped help before assuming syntax.
• Some docs show space-based commands while older tooling may expose colon-style forms.
• API endpoint style can differ by server version (/api/* vs /api/trpc/*).
• API responses can be nested (result.data.json) in tRPC mode.

References

• CLI commands and flags: references/cli.md
• API endpoints and payloads: references/api.md
• Incident actions: references/operator-playbook.md
• Official Dokploy docs: https://docs.dokploy.com/docs/cli and https://docs.dokploy.com/docs/api