Dokploy Api

Dokploy API

Скилл для работы с Dokploy через готовые bash-скрипты. API у Dokploy — tRPC, эндпоинты вида /api/., авторизация через заголовок x-api-key.

Workflow

1. Проверь config/.env. Если нет — запусти onboarding (см. [config/README.md](config/README.md)).
2. Используй готовые методы из scripts/methods/.
3. Для эндпоинта, которого нет в methods/ — ./scripts/dokploy-request.sh METHOD procedure [--data '{...}'].
4. Перед write-операцией прочитай объект через app-status.sh или dokploy-request.sh GET ...one --query 'id=...'.

Authentication

Header: x-api-key: 

Токен делается в Dokploy UI → Settings → API/CLI → Generate Token. Хранится в config/.env (gitignore).

Переменные:

• DOKPLOY_URL — http://host:port или https://host, без trailing slash
• DOKPLOY_API_KEY — long-lived API token

Переменные окружения переопределяют config/.env на один вызов.

Готовые методы

Проекты и серверы

| Скрипт | Назначение | |--------|------------| | methods/project-list.sh | Список проектов с приложениями и compose | | methods/project-create.sh [desc] | Создать проект | | methods/server-list.sh | Список remote-серверов |

Git-провайдеры

| Скрипт | Назначение | |--------|------------| | methods/git-providers-list.sh | Список git-провайдеров (GitHub Apps, GitLab, и т.п.) | | methods/github-repos.sh | Репозитории, доступные GitHub App | | methods/sshkey-list.sh | SSH-ключи Dokploy (для custom git) |

Applications

| Скрипт | Назначение | |--------|------------| | methods/app-create.sh [--server ] [--description ...] | Создать application в environment | | methods/app-set-github-source.sh [branch] [buildPath] | Привязать к GitHub App-провайдеру (автодеплой по push) | | methods/app-set-git-source.sh [branch] [buildPath] [sshKeyId] | Привязать к произвольному git (через SSH-ключ) | | methods/app-set-build-type.sh [--dockerfile path] [--context dir] [--stage name] | Тип билда (dockerfile/nixpacks/...) | | methods/app-update.sh | Обновить произвольные поля (autoDeploy, env, и т.п.) | | methods/app-set-env.sh [envFile] | Записать env-блок (или из stdin) | | methods/app-deploy.sh | Запустить деплой (clone + build + run) | | methods/app-redeploy.sh | Перезапустить из существующего image | | methods/app-stop.sh | Остановить контейнер | | methods/app-start.sh | Запустить остановленный | | methods/app-status.sh [--full] | Сводка/полная карточка application | | methods/app-delete.sh | Удалить app |

Домены

| Скрипт | Назначение | |--------|------------| | methods/domain-create.sh [--port N] [--http-only] [--cert letsencrypt\|none] | Прикрутить домен с Let's Encrypt по умолчанию | | methods/domain-delete.sh | Удалить домен |

Универсальный вызов

./scripts/dokploy-request.sh GET  project.all
./scripts/dokploy-request.sh GET  application.one --query 'applicationId=abc123'
./scripts/dokploy-request.sh POST application.deploy --data '{"applicationId":"abc123"}'
./scripts/dokploy-request.sh POST domain.create --data '{"applicationId":"abc","host":"x.com","https":true,"port":3000,"path":"/","certificateType":"letsencrypt","domainType":"application"}'

Полный сценарий: новый сайт под Dokploy с GitHub-автодеплоем

# 1. Создать проект
./scripts/methods/project-create.sh "MySite"
# → projectId, environmentId

# 2. Найти GitHub-провайдера (githubId) и сервер (serverId, опционально)
./scripts/methods/git-providers-list.sh
./scripts/methods/server-list.sh

# 3. Убедиться что репо доступен GitHub App
./scripts/methods/github-repos.sh  | grep my-repo

# 4. Создать application
./scripts/methods/app-create.sh "mysite"  --server 
# → applicationId

# 5. Привязать GitHub-источник
./scripts/methods/app-set-github-source.sh   esporykhin my-repo main /

# 6. Указать тип билда
./scripts/methods/app-set-build-type.sh  dockerfile --dockerfile Dockerfile --context .

# 7. (опц.) env-переменные
./scripts/methods/app-set-env.sh  /path/to/.env.production

# 8. Прикрутить домен
./scripts/methods/domain-create.sh  mysite.com --port 3000

# 9. Включить autoDeploy и сделать первый деплой
./scripts/methods/app-update.sh  '{"autoDeploy":true,"triggerType":"push"}'
./scripts/methods/app-deploy.sh 

# 10. Дождаться done
until [ "$(./scripts/methods/app-status.sh  | jq -r .applicationStatus)" != "running" ]; do sleep 15; done
./scripts/methods/app-status.sh 

Реестр известных tRPC-процедур

Полного OpenAPI Dokploy не отдаёт. Подтверждённые рабочие эндпоинты (на момент написания):

| Procedure | Method | Назначение | |-----------|--------|------------| | project.all | GET | список проектов | | project.create | POST | создать проект | | server.withSSHKey | GET | список серверов | | gitProvider.getAll | GET | git-провайдеры | | github.getGithubRepositories?githubId=... | GET | репозитории GitHub App | | sshKey.all / sshKey.one?sshKeyId=... | GET | SSH-ключи | | application.create | POST | создать app | | application.one?applicationId=... | GET | карточка app | | application.update | POST | произвольный patch | | application.saveGithubProvider | POST | привязать GitHub-источник | | application.saveGitProvider | POST | привязать custom git | | application.saveBuildType | POST | тип билда | | application.deploy | POST | задеплоить | | application.redeploy | POST | перезапустить из image | | application.stop / application.start | POST | стоп/старт | | application.delete | POST | удалить | | domain.create / domain.delete | POST | домены |

Если нужного эндпоинта нет — пробуй очевидные имена (.all, .one, .create, .update, .delete, и т.п.) через dokploy-request.sh. На отсутствующий путь API возвращает {"code":"NOT_FOUND"}.

Гочи

• application.saveGitProvider требует поле watchPaths:[] (даже пустое).
• application.saveBuildType требует поля herokuVersion и railpackVersion (можно "24"/"latest").
• application.deploy сразу возвращает 200 и стартует фоновый билд. Статус смотри через application.one → applicationStatus: running → done/error.
• На remote-серверах логи деплоя лежат в /etc/dokploy/logs//-.log (через SSH).
• При удалении app вручную из traefik (/etc/dokploy/traefik/dynamic/.yml) Dokploy перегенерирует конфиг при следующем деплое.

Ссылки

• Docs: https://docs.dokploy.com
• Source: https://github.com/Dokploy/dokploy

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: esporykhin
• Source: esporykhin/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.