dokploy

name

dokploy

description

Control a self-hosted Dokploy deployment platform. Deploy, redeploy, start, stop, rollback apps and compose stacks. Manage databases (postgres, mysql, mariadb, mongo, redis), domains, env vars, Docker containers, backups, schedules, mounts, registries, volume backups, and server metrics. Use when the user mentions Dokploy, deploying an app on their server, checking deployment status, managing self-hosted services, or any infrastructure on their VPS.

Dokploy Skill

Control a Dokploy instance via its tRPC API. Full deployment lifecycle — list, deploy, rollback, manage env vars, domains, databases, Docker containers, schedules, mounts, registries, volume backups, notifications, SSH keys, certificates, and more.

Setup

Requires two environment variables (already set in ~/.zshrc):

export DOKPLOY_URL="https://dokploy.kitty-armadillo.ts.net"
export DOKPLOY_API_KEY="..."

Run all scripts from the scripts/ directory (they import api.py locally):

cd ~/.claude/skills/dokploy/scripts
python3 list_projects.py

Known Infrastructure

Projects on this Dokploy instance:

• media — jellyfin, dispatcharr
• automation — postiz, changedetection
• websites — qraft (app)
• ai — openclaw, cc-max-proxy, bifrost
• security — authentik, vaultwarden, blocky, mitmproxy
• sync — syncthing, obsidian-livesync
• tools — termix, glance
• selfhosted — (being migrated to above projects)

Host IP: 139.99.122.178 (single-server setup, no remote servers)

---

Commands Reference

Overview

python3 list_projects.py                          # All projects + environments
python3 list_apps.py                              # All services with status icons
python3 list_apps.py --project <projectId>        # Filter by project
python3 list_apps.py --env <environmentId>        # Filter by environment
python3 search.py "glance"                        # Search all resource types
python3 search.py "api" --type app                # Apps only
python3 search.py "worker" --type compose         # Compose stacks only

Deploy / Lifecycle

# Apps (via app.py)
python3 app.py deploy <applicationId>
python3 app.py redeploy <applicationId> [--title "..."] [--description "..."]
python3 app.py start <applicationId>
python3 app.py stop <applicationId>
python3 app.py reload <applicationId> --app-name <slug>
python3 app.py cancelDeployment <applicationId>
python3 app.py killBuild <applicationId>
python3 app.py markRunning <applicationId>

# Compose stacks (via compose.py)
python3 compose.py deploy <composeId>
python3 compose.py redeploy <composeId> [--title "..."] [--desc "..."]
python3 compose.py start <composeId>
python3 compose.py stop <composeId>
python3 compose.py cancelDeployment <composeId>
python3 compose.py killBuild <composeId>
python3 compose.py isolatedDeployment <composeId>

# Databases (via deploy.py — legacy shorthand)
python3 deploy.py start  <postgresId> --type postgres
python3 deploy.py stop   <mysqlId>    --type mysql
python3 deploy.py deploy <redisId>    --type redis
# types: app (default) | compose | postgres | mysql | mariadb | mongo | redis

Deployment Status

python3 status.py <applicationId>                 # History for an app
python3 status.py <composeId> --type compose      # History for compose stack
python3 status.py --queue                         # Global deployment queue
python3 status.py --all                           # All deployments platform-wide
python3 status.py <id> --limit 5                  # Last N deployments
python3 status.py <id> --by-type <serviceType>    # Filter by service type
python3 status.py --kill <deploymentId>           # Kill a running process
python3 status.py --remove <deploymentId>         # Remove a deployment record

Rollback

python3 rollback.py <applicationId>               # List available images
python3 rollback.py <applicationId> --image <tag> # Roll back to image
python3 rollback.py <applicationId> --delete <rollbackId>  # Delete a rollback entry

Compose File

python3 compose_file.py get <composeId>           # Print current compose file
python3 compose_file.py set <composeId> --file docker-compose.yml
python3 compose_file.py set <composeId>           # Read from stdin
python3 compose_file.py edit <composeId> /tmp/edit.yml  # Save locally to edit
# After editing: set it back + redeploy

Compose Stack Management

python3 compose.py get <composeId>
python3 compose.py services <composeId>
python3 compose.py create --name "mystack" --env <environmentId> --app-name <slug> --file docker-compose.yml
python3 compose.py update <composeId> [--name ...] [--file ...]
python3 compose.py move <composeId> --env <targetEnvironmentId>
python3 compose.py rm <composeId>
python3 compose.py search <projectId>
python3 compose.py templates                      # List available templates
python3 compose.py deployTemplate --env <envId> --id <templateId>
python3 compose.py getConvertedCompose <composeId>
python3 compose.py getTags <composeId>
python3 compose.py loadMountsByService <composeId> <serviceName>
python3 compose.py randomizeCompose <composeId>
python3 compose.py refreshToken <composeId>
python3 compose.py fetchSourceType <composeId>
python3 compose.py disconnectGitProvider <composeId>
python3 compose.py import <composeId> <base64>
python3 compose.py processTemplate <composeId> <base64>

Environment Variables

python3 env.py get <applicationId>
python3 env.py get <postgresId> --type postgres
python3 env.py set <applicationId> "KEY=val\nKEY2=val2"
python3 env.py set <redisId> "REDIS_PASSWORD=secret" --type redis
# types: app | compose | postgres | mysql | mariadb | mongo | redis

# Full app env + build args (via app.py)
python3 app.py saveEnvironment <applicationId> --env "KEY=val" [--build-args "..."] [--create-env-file]

Projects

python3 project.py ls
python3 project.py get <projectId>
python3 project.py create --name "myproject" [--desc "..."]
python3 project.py update <projectId> --name "new name"
python3 project.py rm <projectId>

Environments

python3 environment.py ls --project <projectId>
python3 environment.py get <environmentId>
python3 environment.py create --project <projectId> --name "production" [--desc "..."]
python3 environment.py duplicate <environmentId> --name "staging"
python3 environment.py update <environmentId> [--name ...] [--desc ...]
python3 environment.py search <query> [--project <projectId>]
python3 environment.py rm <environmentId>

Apps (Applications)

python3 app.py get <applicationId>
python3 app.py create --name "myapp" --app-name <slug> --env <environmentId>
python3 app.py update <applicationId> [--name ...] [--desc ...]
python3 app.py move <applicationId> --env <targetEnvironmentId>
python3 app.py rm <applicationId>
python3 app.py search --project <projectId>

# Build configuration
python3 app.py saveBuildType <applicationId> --build-type dockerfile [--dockerfile ...]
python3 app.py saveDockerProvider <applicationId> --image nginx:latest
python3 app.py saveGithubProvider <applicationId> --github-id <id> --owner org --repo name --branch main
python3 app.py saveGitlabProvider <applicationId> --gitlab-id <id> --owner org --repo name --branch main
python3 app.py saveBitbucketProvider <applicationId> --bitbucket-id <id> --owner org --repo name --repo-slug name --branch main
python3 app.py saveGitProvider <applicationId> --url https://... --branch main [--ssh-key-id ...]
python3 app.py saveGiteaProvider <applicationId> --gitea-id <id> --owner org --repo name --branch main

# Traefik
python3 app.py readTraefikConfig <applicationId>
python3 app.py updateTraefikConfig <applicationId> --config "..."
python3 app.py readAppMonitoring <applicationId>

# Token management
python3 app.py refreshToken <applicationId>
python3 app.py disconnectGitProvider <applicationId>

Databases (CRUD)

python3 database.py ls --project <projectId> [--type postgres]
python3 database.py get <dbId> --type postgres
python3 database.py create --type postgres --name "mydb" --env <environmentId> \
  --db-name mydb --db-user myuser --db-pass secret
python3 database.py update <dbId> --type postgres [--name ...] [--db-pass ...]
python3 database.py move <dbId> --type postgres --env <targetEnvironmentId>
python3 database.py rebuild <dbId> --type mysql
python3 database.py reload <dbId> --type redis --app-name <slug>
python3 database.py save-env <dbId> --type mongo --env "KEY=val"
python3 database.py save-external-port <dbId> --type postgres --port 5433
python3 database.py search --project <projectId> --type postgres
python3 database.py change-status <dbId> --type postgres --status idle
python3 database.py rm <dbId> --type postgres
# types: postgres | mysql | mariadb | mongo | redis

Domains

python3 domain.py ls <applicationId>              # List domains for app
python3 domain.py ls-compose <composeId>          # List domains for compose stack
python3 domain.py get <domainId>
python3 domain.py add <applicationId> myapp.example.com --port 3000
python3 domain.py update <domainId> --host myapp.example.com [--port ...] [--https ...]
python3 domain.py validate --domain myapp.example.com
python3 domain.py can-gen --server <serverId>     # Check if traefik.me domains available
python3 domain.py gen <appName>                   # Auto-generate traefik domain
python3 domain.py rm <domainId>

Ports

python3 port.py get <portId>
python3 port.py add <applicationId> --target 3000 --published 3000 [--protocol tcp] [--publish-mode ingress]
python3 port.py update <portId> --target 3000 --published 3000
python3 port.py rm <portId> --confirm

Redirects

python3 redirects.py get <redirectId>
python3 redirects.py add <applicationId> --regex "^/old(.*)" --replacement "/new$1" [--permanent]
python3 redirects.py update <redirectId> --regex "..." --replacement "..."
python3 redirects.py rm <redirectId> --confirm

Security Rules (HTTP Basic Auth)

python3 security_rule.py get <securityId>
python3 security_rule.py add <applicationId> --username admin --password secret
python3 security_rule.py update <securityId> --username admin --password newsecret
python3 security_rule.py rm <securityId>

Mounts

python3 mounts.py ls --service-id <id> --service-type application
python3 mounts.py ls-named --app <applicationId>  # Named volumes only
python3 mounts.py get <mountId>
python3 mounts.py create --service-id <id> --service-type application --mount-path /data --host-path /srv/data
python3 mounts.py create --service-id <id> --service-type application --mount-path /config/app.json \
  --file-path /config/app.json --content '{"key":"val"}'
python3 mounts.py update <mountId> [--content ...] [--mount-path ...]
python3 mounts.py rm <mountId>
# service-type: application | compose | postgres | mysql | mariadb | mongo | redis

Schedules

python3 schedules.py ls --app <serviceId> --schedule-type application
python3 schedules.py get <scheduleId>
python3 schedules.py run <scheduleId>             # Trigger manually
python3 schedules.py create --app <serviceId> --schedule-type application \
  --name "cleanup" --command "node cleanup.js" --cron "0 2 * * *"
python3 schedules.py update <scheduleId> --cron "0 3 * * *"
python3 schedules.py rm <scheduleId>
# schedule-type: application | compose | server | dokploy-server

Preview Deployments

python3 preview_deployments.py ls --app <applicationId>
python3 preview_deployments.py create --app <applicationId> --pr <pullRequestId>
python3 preview_deployments.py redeploy <previewDeploymentId>
python3 preview_deployments.py rm <previewDeploymentId>

Docker Containers

python3 docker_containers.py ls                              # All containers
python3 docker_containers.py ls --app <appName> --app-type <type>  # By app label
python3 docker_containers.py ls --match <appName>            # Fuzzy name match
python3 docker_containers.py ls --service <appName>          # Swarm services
python3 docker_containers.py ls --stack <appName>            # Stack containers
python3 docker_containers.py config <containerId>            # Inspect container config
python3 docker_containers.py restart <containerId>

Server Management

python3 server.py ls                              # List all servers
python3 server.py get <serverId>                  # Server details
python3 server.py create --name "vps1" --ip 1.2.3.4 [--ssh-key-id <id>]
python3 server.py update <serverId> [--name ...] [--ip ...]
python3 server.py setup <serverId>                # Initialize server
python3 server.py setup-monitoring <serverId>
python3 server.py validate <serverId>
python3 server.py remove <serverId> --confirm
python3 server.py metrics --url <url> --token <token>
python3 server.py count
python3 server.py build-servers                   # Servers usable for builds
python3 server.py with-ssh-key                    # Servers with SSH keys
python3 server.py security <serverId>
python3 server.py default-command <serverId>

Monitoring

python3 monitoring.py app <appName>               # App-level CPU/memory stats
python3 monitoring.py server <serverId>           # Server-level metrics
# appName = the container name e.g. "selfhosted-glance-ea3xfz"

Registries

python3 registry.py ls
python3 registry.py get <registryId>
python3 registry.py create --name "my-registry" --url registry.example.com \
  --username user --password pass --type selfHosted
python3 registry.py update <registryId> --password newpass
python3 registry.py test --url registry.example.com --username user --password pass
python3 registry.py test-by-id <registryId>
python3 registry.py rm <registryId> --confirm
# types: selfHosted | dockerhub | ghcr

SSH Keys

python3 sshkey.py ls
python3 sshkey.py get <sshKeyId>
python3 sshkey.py create --name "my-key" --private-key "$(cat ~/.ssh/id_ed25519)"
python3 sshkey.py generate [--type ed25519]       # Generate new key pair
python3 sshkey.py update <sshKeyId> [--name ...] [--description ...]
python3 sshkey.py rm <sshKeyId> --confirm

Certificates

python3 certificates.py ls
python3 certificates.py get <certificateId>
python3 certificates.py add --name "mycert" --cert-file /path/cert.pem --key-file /path/key.pem
python3 certificates.py rm <certificateId> --confirm

Backups (Database)

python3 backup.py create --schedule "0 2 * * *" --prefix "backup" \
  --destination-id <destId> --database mydb --database-type postgres
python3 backup.py one <backupId>
python3 backup.py update <backupId> --schedule "0 3 * * *" ...
python3 backup.py run <backupId> --type postgres  # Trigger manual backup
python3 backup.py run <backupId> --type mysql
python3 backup.py run <backupId> --type mariadb
python3 backup.py run <backupId> --type mongo
python3 backup.py run <backupId> --type compose
python3 backup.py run <backupId> --type web-server
python3 backup.py ls <destinationId>              # List backup files at destination
python3 backup.py remove <backupId>

Backup Destinations (S3-compatible)

python3 destination.py ls
python3 destination.py get <destinationId>
python3 destination.py create --name "s3-backups" --bucket mybucket --region us-east-1 \
  --access-key AKIA... --secret-key ... --endpoint https://s3.amazonaws.com
python3 destination.py test --name "..." --bucket mybucket --region us-east-1 \
  --access-key AKIA... --secret-key ... --endpoint https://...
python3 destination.py update <destinationId> --name "..." --bucket ... (all fields required)
python3 destination.py rm <destinationId>

Volume Backups

python3 volume_backups.py ls --service-id <id> --service-type application
python3 volume_backups.py get <volumeBackupId>
python3 volume_backups.py create --name "vol-backup" --volume-name myvolume \
  --prefix "backup" --cron "0 3 * * *" --destination-id <destId>
python3 volume_backups.py update <volumeBackupId> [--cron ...] [--enabled] [--no-enabled]
python3 volume_backups.py run <volumeBackupId>    # Trigger manually
python3 volume_backups.py rm <volumeBackupId>
# service-type: application | compose | postgres | mysql | mariadb | mongo | redis

Notifications

python3 notification.py ls
python3 notification.py get <notificationId>
python3 notification.py rm <notificationId>
python3 notification.py email-providers           # List email providers

# Create notifications (provider-specific required fields)
python3 notification.py create discord --name "alerts" --webhook-url "https://discord.com/..."
python3 notification.py create slack --name "alerts" --webhook-url "https://hooks.slack.com/..."
python3 notification.py create telegram --name "alerts" --bot-token "..." --chat-id "..."
python3 notification.py create email --name "alerts" --smtp-host mail.example.com \
  --smtp-port 587 --smtp-user user --smtp-pass pass --from-address [e-mail] \
  --to-addresses [e-mail]
python3 notification.py create gotify --name "alerts" --server-url https://... --token "..."
python3 notification.py create ntfy --name "alerts" --server-url https://ntfy.sh --topic mytopic
python3 notification.py create pushover --name "alerts" --user-key "..." --app-token "..."
python3 notification.py create teams --name "alerts" --webhook-url "https://..."
python3 notification.py create lark --name "alerts" --webhook-url "https://..."
python3 notification.py create resend --name "alerts" --api-key "re_..." \
  --from-address noreply@... --to-addresses admin@...
python3 notification.py create custom --name "alerts" --endpoint https://...

# Test / update follow the same pattern
python3 notification.py test discord <notificationId>
python3 notification.py update discord <notificationId> --webhook-url "..."

Maintenance (Docker Cleanup)

python3 maintenance.py clean --target images      # Remove unused images
python3 maintenance.py clean --target containers  # Remove stopped containers
python3 maintenance.py clean --target volumes     # Remove unused volumes
python3 maintenance.py clean --target builder     # Clean build cache
python3 maintenance.py clean --target queues      # Clear all deployment queues
python3 maintenance.py clean --target all         # Full cleanup (scheduled in bg)

---

Finding IDs

python3 search.py "glance" | grep "id:"
python3 list_apps.py | grep "glance"

Service Types Quick Reference

--type	Service	ID field
app (default)	Application	applicationId
compose	Docker Compose stack	composeId
postgres	PostgreSQL	postgresId
mysql	MySQL	mysqlId
mariadb	MariaDB	mariadbId
mongo	MongoDB	mongoId
redis	Redis	redisId

All Scripts

Script	Purpose
api.py	Shared tRPC client (not called directly)
list_projects.py	Projects + environment overview
list_apps.py	All services with status
search.py	Cross-resource search
deploy.py	Deploy/start/stop/reload any service (legacy shorthand)
status.py	Deployment history, queue, kill, remove
rollback.py	List images, rollback, delete entry
compose_file.py	Read/write compose YAML
env.py	Get/set environment variables
project.py	Project CRUD
environment.py	Environment CRUD + duplicate
app.py	Application CRUD + full lifecycle + provider config
compose.py	Compose stack CRUD + full lifecycle + templates
database.py	Database CRUD + move/rebuild/reload/search (all types)
domain.py	Domain management
port.py	Port mapping CRUD
redirects.py	HTTP redirect rules
security_rule.py	HTTP basic auth rules
mounts.py	Volume/file mount management
schedules.py	Cron/scheduled task management
preview_deployments.py	PR preview deployments
docker_containers.py	Container list, config, restart
server.py	Server CRUD + setup + metrics
monitoring.py	App + server metrics
registry.py	Container registry management + test
sshkey.py	SSH key management + generate
certificates.py	SSL certificate management
backup.py	Database backup CRUD + manual triggers
destination.py	S3-compatible backup destination CRUD
volume_backups.py	Volume backup management
notification.py	Notification channels (11 providers)
maintenance.py	Docker cleanup operations