Dokploy
The Dokploy courier draws your Dokploy as a town and runs the actions you allow. It reads the API of Dokploy and receives its notifications: nothing is installed on the Dokploy side, and nothing in your projects changes.
What it never does
Section titled “What it never does”- It never acts on its own, and a webhook never triggers an action. Actions come from a person in the town, in a district whose actions an admin turned on.
- It never acts with the API key it reads with: actions use the deploy API key only, and a town without that key is read-only.
- It never shows, logs or sends a key to the browser. Keys are stored encrypted in the town hall, never in
myrtille.yaml. - It never keeps what it does not need: every answer of Dokploy is filtered by a list of allowed fields, so environment variables, registry and basic auth passwords, compose files, build arguments and secrets, deployment titles and error messages are dropped before anything else sees them.
What you need
Section titled “What you need”- Dokploy 0.26.0 or later, reachable from the town hall over HTTPS.
- A dedicated member of your Dokploy organisation for the town (below), and its API keys.
The keys hold all the power of their user
Section titled “The keys hold all the power of their user”Dokploy API keys have no scope: a key carries every permission of the user who created it. So both keys Myrtille asks for can do whatever that user can do: with the member role, that is stopping, redeploying and changing the environment variables of every service the member reaches. Myrtille uses the first key only to read and the second only for the actions you allow, but it cannot prove that a key could not do more. The town hall says so each time it checks the keys (the setup of the town, myrtille init and myrtille doctor): every key that works carries the warning unscoped_key. A warning is not a failure.
Keep that power small:
- In Dokploy, an admin invites a dedicated member for the town.
- The admin gives that member access to the API, and to the projects and services of the town only. Nothing else: no creation or deletion of projects and services, no Docker, Traefik, SSH keys or Git providers.
- Signed in as that member, create the keys in Settings > Profile > API/CLI.
Never give the key of the owner or of an admin of the organisation.
| Key | Used for |
|---|---|
| API key | Required. The version, discovery, polling, the history of deployments. |
| Deploy API key | Optional. Deploy, redeploy, restart and stop: the actions of operators. Leave it out to only read. |
When you save the keys, the town hall checks the API key on the version and on the projects, and the deploy API key on the version only: listing the projects makes Dokploy load the environment variables of every service before Myrtille drops them, so the deploy key is never used to read.
Give the keys in the setup of the town (choose Dokploy in the step of the tool), or with myrtille init --tool dokploy (they are typed without echo, or read from DOKPLOY_API_KEY and DOKPLOY_DEPLOY_API_KEY). A stored key is never sent to another Dokploy address: changing the address asks for every key again.
How Dokploy becomes a town
Section titled “How Dokploy becomes a town”| Dokploy | Town |
|---|---|
| Project | Building |
| Environment | District |
| Application | service citizen |
| Compose service | service citizen |
The status Dokploy gives a service says how its last deployment went: done reads running, a running deployment running with the message deploying, error reads error, and idle (never deployed, or stopped) reads offline.
The webhook
Section titled “The webhook”Dokploy sends its notifications to https://<town hall>/hooks/<courier id>/<token>, an address with a random token that the setup shows once. In Dokploy, Settings > Notifications: add a Custom notification with that address, tick “App Deploy” and “App Build Error”, and save.
A webhook is only a hint: Dokploy does not sign it, and whoever holds its address can send one. The outcome of a build is read again through the API of Dokploy before it reaches the town, and dropped when the API does not confirm it. The free text of every notification is never carried over.
Polling
Section titled “Polling”At rest, every 45 seconds, one request gives the status of every service. A service that deploys is watched every 3 seconds while its deployment runs, and for a minute after an action launched from the town. The client never sends more than 2 requests a second to an instance.
Known limits
Section titled “Known limits”- A container that crashes after a successful deployment still reads
running: Dokploy gives the outcome of the last deployment, not the state of the containers. - No cancel of a deployment (Dokploy cancels in its cloud version only) and no restart of a compose service (Dokploy has no reload for it).
- Databases, previews, servers, logs and environment variables are not handled yet; the Logs tab of a citizen links to its page in Dokploy.
- Citizens have no public links yet: the projects Dokploy lists do not give the domains.