dokploy-management

name

dokploy-management

description

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.

Dokploy Management

Comprehensive guide for managing Dokploy instances via CLI, API, and production deployment patterns.

CLI Options

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.

Quick Reference (Custom CLI)

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

Installation

Custom CLI (Recommended)

# 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

Official CLI (Limited)

npm install -g @dokploy/cli

Authentication

Custom 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 File Location

~/.config/dokploy/config.json:

{
  "url": "https://panel.example.com",
  "token": "your-token",
  "defaultProjectId": "optional",
  "defaultEnvironmentId": "optional"
}

Core Workflows

Workflow 1: Project Setup

# 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>

Workflow 2: Docker Compose Stack

# 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>

Workflow 3: Database Setup

# 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

Workflow 4: Domain Configuration

# 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

Workflow 5: CI/CD with GitHub Actions

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 }}"}'

Command Reference (Custom CLI)

Auth Commands

dokploy auth login --url <url> --token <token>
dokploy auth logout
dokploy auth status
dokploy auth set-default --project <id> --environment <id>

Project Commands

dokploy project list
dokploy project get <projectId>
dokploy project create --name <name> [--description <desc>]
dokploy project delete <projectId> [--force]

Application Commands

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

Compose Commands

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

Domain Commands

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>

Database Commands

# 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]

Server Commands

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]

Docker Commands

dokploy docker containers [--server <serverId>]
dokploy docker restart <containerId> [--server <serverId>]

JSON Output

All commands support --json for machine-readable output:

dokploy project list --json | jq '.[].projectId'
dokploy app get abc123 --json > app-config.json

API Reference

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.

Important Gotchas

Compose Source Types

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".

Compose File Compatibility

Dokploy does NOT support env_file directive in docker-compose.yml. You must:

1. Inline all environment variables in the environment section
2. Use YAML anchors (&anchor / *anchor) for shared env vars
3. Set sensitive values via Dokploy's env var system (compose.update with env field)

Before (won't work):

services:
  app:
    env_file:
      - .env

After (works):

services:
  app:
    environment:
      DB_HOST: "${DB_HOST}"
      DB_PASS: "${DB_PASS}"

Domain + Deploy Order

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!

Network Requirements

All services must be on dokploy-network (external) to be routable:

services:
  web:
    networks:
      - dokploy-network

networks:
  dokploy-network:
    external: true

Troubleshooting

Authentication Issues

# Check current auth
dokploy auth status

# Re-authenticate
dokploy auth login --url https://... --token ...

# Verify environment variables are set
env | grep DOKPLOY

Deployment Failures

1. Check application/compose status: dokploy compose get <id> or dokploy app get <id>
2. Check deployment history via API for error messages
3. Common errors:
   • "Github Provider not found" → Set sourceType: "raw" for direct compose files
   • "env_file not found" → Inline env vars, Dokploy doesn't support env_file
   • Container not routing → Ensure service is on dokploy-network and redeploy after adding domain
4. Verify health endpoint responds
5. Check Dokploy web UI for deployment logs
6. Ensure dokploy-network exists: docker network ls

Missing IDs

Run 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}'

Resources

• Custom CLI: ./cli/ directory in this skill
• Official CLI: https://github.com/Dokploy/cli
• Official Docs: https://docs.dokploy.com
• API Spec: Available at https://your-instance/api/settings.getOpenApiDocument

Example: Full Compose Deployment

Complete 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