Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Nettalco/dokploy/llms.txt

Use this file to discover all available pages before exploring further.

The Settings panel is the central place for server administration in Dokploy. From here you can monitor infrastructure health, apply updates, free up disk space by pruning unused Docker resources, configure the master SSH key for remote server connections, manage the Traefik reverse-proxy, and enable GPU workloads — all without leaving the dashboard.
Some settings are only available in self-hosted mode. Endpoints that are Cloud-only or self-hosted-only are called out in each section below. When settings.isCloud returns true, operations marked self-hosted only are silently skipped or return early.

​
System Health

Use the health and version endpoints to confirm Dokploy is running correctly and to stay informed about available updates.
  • settings.health — Executes a lightweight SELECT 1 against the database. Returns { status: "ok" } on success. Suitable for load-balancer liveness probes and uptime monitors (public endpoint, no authentication required).
  • settings.checkInfrastructureHealth — Checks the health of Postgres, Redis, and Traefik simultaneously. Returns a structured object with a status field for each service ("healthy" / "unhealthy"). On Dokploy Cloud all three are reported as healthy automatically. Requires admin role.
  • settings.getDokployVersion — Returns the currently running Dokploy package version string (e.g., "0.18.4").
  • settings.getReleaseTag — Returns the Docker image tag used for the running Dokploy container (e.g., "canary" or "latest").
const { status } = await trpc.settings.health.query();           // "ok"
const version     = await trpc.settings.getDokployVersion.query(); // "0.18.4"
const tag         = await trpc.settings.getReleaseTag.query();     // "latest"

​
Server IP Configuration

Dokploy stores the server’s public IP address to use as the default target for domain routing and certificate generation. If your server’s IP changes (for example, after a provider migration), update it here.
  • settings.getIp — Returns the stored serverIp value from the web server settings record.
  • settings.updateServerIp — Persists a new IP address. Requires admin role. No-op on Cloud.
const ip = await trpc.settings.getIp.query();
// "203.0.113.42"

await trpc.settings.updateServerIp.mutate({ serverIp: "203.0.113.99" });

​
Updating Dokploy

Dokploy can update itself in-place by pulling a newer Docker image and restarting the service. The update flow is two steps: check for an update, then apply it.
1

Check for updates

Call settings.getUpdateData to compare the running version against the latest published release. The response includes updateAvailable: boolean and latestVersion: string.
const update = await trpc.settings.getUpdateData.mutate();
if (update.updateAvailable) {
  console.log(`New version available: ${update.latestVersion}`);
}
2

Apply the update

Call settings.updateServer to pull the new image and restart the Dokploy Docker service. Dokploy runs the update in the background (docker service update --force --image dokploy/dokploy:<version> dokploy) so the request returns immediately. Expect a brief downtime while the container restarts.
await trpc.settings.updateServer.mutate();
Both endpoints are self-hosted only. On Cloud they return without performing any action.

​
Docker Cleanup

Over time Docker accumulates unused images, dangling volumes, stopped containers, and build cache that can consume significant disk space. Dokploy exposes granular cleanup endpoints so you can reclaim space safely.

Clean Unused Images

Removes Docker images that are not referenced by any container.Endpoint: settings.cleanUnusedImages
await trpc.settings.cleanUnusedImages.mutate({
  serverId: "srv_abc", // optional — omit for the local server
});

Clean Unused Volumes

Removes Docker volumes not attached to any container.Endpoint: settings.cleanUnusedVolumes
await trpc.settings.cleanUnusedVolumes.mutate({ serverId: "srv_abc" });

Clean Stopped Containers

Removes all containers in the exited or created state.Endpoint: settings.cleanStoppedContainers
await trpc.settings.cleanStoppedContainers.mutate({ serverId: "srv_abc" });

Clean Docker Builder Cache

Flushes the BuildKit build cache, freeing space consumed by intermediate build layers.Endpoint: settings.cleanDockerBuilder
await trpc.settings.cleanDockerBuilder.mutate({ serverId: "srv_abc" });

Docker System Prune

Runs docker system prune followed by a builder prune — removes images, build cache, and stopped containers in one shot.Endpoint: settings.cleanDockerPrune
await trpc.settings.cleanDockerPrune.mutate({ serverId: "srv_abc" });

Clean Everything

Executes all cleanup operations in a single background job, returning immediately to avoid gateway timeouts. Sends Docker cleanup notifications to the organization.Endpoint: settings.cleanAll
await trpc.settings.cleanAll.mutate({ serverId: "srv_abc" });

​
Automated Docker cleanup

Enable or disable a scheduled automatic Docker cleanup job with settings.updateDockerCleanup. When enabled, Dokploy registers a recurring cron job that runs the full cleanup routine and dispatches notifications. 
await trpc.settings.updateDockerCleanup.mutate({
  enableDockerCleanup: true,
  serverId: "srv_abc", // optional
});
You can also retrieve Docker disk usage statistics with settings.getDockerDiskUsage (self-hosted only) to understand where space is being consumed before running a cleanup.

​
Deployment Queue

The deployment queue is backed by Redis. If deployments become stuck or the queue grows unexpectedly, the following endpoints let you reset queue state without a full restart.
  • settings.cleanAllDeploymentQueue — Drains all pending deployments from every queue. Use this to unblock a frozen pipeline. Self-hosted only.
  • settings.cleanRedis — Runs FLUSHALL on the Dokploy Redis container, wiping all queue data and cached state. Use as a last resort when the queue cannot be drained gracefully. Self-hosted only.
  • settings.reloadRedis — Recreates the dokploy-redis Docker service (equivalent to a container restart) without clearing data. Self-hosted only.
// Drain the queue
await trpc.settings.cleanAllDeploymentQueue.mutate();

// Flush Redis
await trpc.settings.cleanRedis.mutate();

// Restart Redis container
await trpc.settings.reloadRedis.mutate();

​
SSH Private Key

Dokploy uses a master SSH private key to authenticate against remote servers. This key is stored encrypted in the web server settings and used whenever Dokploy needs to execute commands on or transfer files to a registered remote server.
  • settings.saveSSHPrivateKey — Stores (or replaces) the PEM-encoded private key. Requires admin role. Self-hosted only.
  • settings.cleanSSHPrivateKey — Removes the stored key, setting it to null. Use this to rotate the key before uploading a new one.
await trpc.settings.saveSSHPrivateKey.mutate({
  sshPrivateKey: "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
});

// Rotate: remove old key first
await trpc.settings.cleanSSHPrivateKey.mutate();
// Then save the new key
await trpc.settings.saveSSHPrivateKey.mutate({ sshPrivateKey: newKey });

​
Web Server Settings

settings.getWebServerSettings returns the full web server configuration record, including host, HTTPS status, Let’s Encrypt email, server IP, SSH key presence, Docker cleanup toggle, monitoring configuration, and build concurrency limits. This endpoint is self-hosted only and returns null on Cloud. 
const settings = await trpc.settings.getWebServerSettings.query();
settings.reloadServer restarts the dokploy Docker service in place (equivalent to docker service update --force dokploy). This is useful after changing environment variables or configuration files that require a process restart. Self-hosted only. 
await trpc.settings.reloadServer.mutate();

​
GPU Support

For workloads that require GPU acceleration (ML inference, video transcoding, etc.), Dokploy can install and configure the NVIDIA Container Runtime on a server.
  • settings.setupGPU — Installs the NVIDIA Container Toolkit and configures Docker to expose GPU resources. Requires admin role. On Cloud, a serverId must be provided.
  • settings.checkGPUStatus — Returns a detailed report including driver version, CUDA support, available GPU count, memory info, and whether the NVIDIA runtime is configured in Docker.
// Install GPU support on a remote server
await trpc.settings.setupGPU.mutate({ serverId: "srv_gpu01" });

// Check GPU status
const gpu = await trpc.settings.checkGPUStatus.query({ serverId: "srv_gpu01" });
console.log(gpu.gpuModel, gpu.cudaVersion, gpu.availableGPUs);

​
Cloud Mode

Two endpoints expose whether the running Dokploy instance is a Cloud deployment or a self-hosted one, and whether the active organization has any active resources.
  • settings.isCloud — Returns true when the IS_CLOUD environment flag is set. This is a public endpoint (no authentication required) and is used by the frontend to conditionally hide self-hosted-only UI elements.
  • settings.isUserSubscribed — Returns true when the active organization has at least one registered server or project. Dokploy Cloud uses this to determine whether the organization is active.
const cloud      = await trpc.settings.isCloud.query();
const subscribed = await trpc.settings.isUserSubscribed.query();
When isCloud is true, many settings endpoints — such as getWebServerSettings, updateServerIp, saveSSHPrivateKey, cleanRedis, cleanAllDeploymentQueue, reloadServer, and all Docker cleanup operations — are no-ops or return early. Management of Cloud infrastructure is handled by the Dokploy platform rather than by the individual user.

Build docs developers (and LLMs) love

Get started for freeTalk to us