Dokploy

Reads deploy targets and manages seats on your servers.

Capability: hosting · Hosting. This is a generic capability: every enabled instance receives the same one-way pushes, so several can be connected side by side.

Vendor site · Vendor docs

Configure Dokploy in Atrium → (admins only)

Setup

Atrium reads deploy targets and manages seats on your Dokploy server from group membership. Point it at the Dokploy API with an admin API key.

Note your Dokploy URL. Base URL of the Dokploy API (e.g. https://dokploy.delphi-dialogue.com).
Create an API key. Dokploy → Settings → API/CLI → Generate an API key with project + member permissions. Copy it once.
Paste URL + key below. The key is stored encrypted (AES-256-GCM).

What you paste back into Atrium

In order, the values the steps above produce:

Dokploy URL
API key

How it works

Dokploy is where the apps Atrium publishes actually run, so Atrium reads deploy targets from it and manages who has a seat on it. Joining an app's developer group invites the person into Dokploy scoped to that app's project and its pinned service, rather than giving them the whole server. This is intended behaviour, not drift.

What Atrium does, and when

When this happens	Atrium does this
An app's deploy target is needed	Reads projects and services from the Dokploy API to resolve where the app lives.
Someone joins an app's developer group	Invites them into Dokploy and scopes them to that app's project plus its one pinned service.
Someone leaves	Removes the seat again, so Dokploy access follows group membership rather than accumulating.
A DNS connector has no ingress IP set	Hosting is the intended source of that address, which is why the DNS connector's ingress-IP field is an optional override rather than something an admin has to hunt down.

Guarantees and limits

Seat provisioning has a per-app off switch (syncDokploy: false) rather than being all-or-nothing. Disabling the whole connector to stop one app's seats is the wrong lever.
Hosting is a generic capability: every enabled instance receives the push.
The API key is encrypted at rest (AES-256-GCM) and never returned to the browser.

What "Test connection" proves

Calls the Dokploy project-list endpoint, the same read the reconciler uses, with the API key in the x-api-key header and a 15-second timeout. Any 2xx is treated as proof the URL and key pair is valid.

Troubleshooting

Symptom	Cause	Fix
Test connection returns 401 or 403.	The API key was revoked or regenerated in Dokploy, or it lacks project scope.	Generate a fresh key with project and member permissions and paste it here.
People are invited into Dokploy but see nothing.	The seat is scoped to a project or service that does not exist under the key's visibility.	Confirm the app's Dokploy project and pinned service resolve under this key, using the same project list the probe reads.
Merging a pull request does not deploy.	Almost always a webhook problem on the git host rather than a connector problem. An app can have autoDeploy enabled and still have no active push hook.	Check the repository's webhooks first, then trigger the deploy through Dokploy's API directly to confirm the app itself is healthy.

Required scopes

Grant the credential exactly these scopes; they are the least-privilege set the connector needs:

API key with project + member read/write on the target Dokploy server

Configuration fields

Field	Type	Required	Notes
`url` Dokploy URL	`text`	yes	Base URL of the Dokploy API. Maps to ATRIUM_DOKPLOY_URL. e.g. `https://dokploy.delphi-dialogue.com`
`apiKey` API key	`password` secret	yes	Dokploy API key with project + member scope. Maps to ATRIUM_DOKPLOY_API_KEY. e.g. `…`

Operating notes

Secret fields are encrypted at rest (AES-256-GCM) and never returned to the client. Editing an instance and leaving a secret field masked keeps the stored value.
Adding a connector from the marketplace creates a disabled, credential-less instance ("Added, not yet connected"); it does nothing until an admin opens it, pastes credentials, and enables it.
Use Test connection on the instance page before enabling: it performs a read-only probe with the credentials you entered.
Connector credentials live in the Atrium database, not in container env vars; changing them here takes effect without a redeploy (within the resolver's 30-second cache).