skip to content
wihan.dev
view as markdown
browse the dokploy docs

Dokploy Provider

Manage Dokploy resources with Terraform:

  • Projects and environments, with shared environment variables and tags
  • Applications from a GitHub App, a GitLab project, a Bitbucket repository, a Gitea repository, a plain git repository, or a Docker image, with preview deployment, rollback, build server settings, and Docker Swarm settings (replicas, rolling updates, health checks, placement)
  • Compose services: docker-compose projects and Docker Swarm stacks, from the same sources or an inline compose file
  • Databases: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, and LibSQL, with the same Swarm settings
  • Routing: domains, published ports, Traefik redirects, HTTP basic auth, and TLS certificates
  • Storage: bind, volume, and file mounts on any service
  • Backups: S3-compatible destinations, scheduled database dumps, Docker volume archives, and a scheduled backup of the Dokploy host
  • Schedules: cron jobs on a service, a remote server, or the Dokploy host
  • Networks: Docker bridge and overlay networks, attached to any service
  • Servers: remote worker and build servers, and the SSH keys that reach them
  • Git providers: GitLab, Bitbucket, and Gitea connections, and lookups of GitHub Apps
  • Registries: container registry logins for private images and built images
  • Notifications: Slack, Discord, Telegram, email, Resend, Gotify, ntfy, Mattermost, Lark, Microsoft Teams, Pushover, and custom webhooks
  • Vault providers: HashiCorp Vault or OpenBao, Infisical, AWS Secrets Manager, Doppler, Azure Key Vault, Scaleway, Phase.dev, and AWS Systems Manager Parameter Store connections for runtime secrets
  • Organization and access: the organization record, users with an initial password, per-user permissions, and API keys
  • AI settings: OpenAI-compatible endpoints for Dokploy’s AI features
  • Connection checks: verify_connection tests the credentials of a registry, a destination, an AI endpoint, a git provider, or a notification channel before the write
  • Lookups: data sources for a record that Terraform does not own, including the children of a service (mounts, ports, redirects, security, backups, schedules), AI settings, and the notification channels

Each service resource deploys on change. Each resource supports terraform import, except dokploy_api_key, whose key Dokploy returns only once.

The provider works with Terraform 1.5 or later and with OpenTofu. The write-only companions of the secret attributes (<name>_wo) need Terraform 1.11 or later; a configuration without them works on 1.5. The provider targets Dokploy v0.30.8. The acceptance suite tests the latest Dokploy release on every pull request and every night. The suite does not test older releases. A server older than the pinned version can reject a field that a newer Dokploy introduced. If your server is older, upgrade it to the pinned version or later before you apply.

Stability

The provider follows semantic versioning from v1.0.0:

  • A minor release adds resources, data sources, and attributes. A configuration and a state from the previous minor release load with an empty plan.
  • A change that removes or renames an attribute, changes a default, or changes what an existing attribute does is a breaking change. It needs a major release, and the upgrade guide shows the old and the new configuration.
  • A deprecated attribute stays for at least one minor release and prints a warning at plan time before a major release removes it.
  • The Dokploy compatibility pin moves in minor releases.

Pin the minor version, for example ~> 1.8, to get fixes and additions without a breaking change. The changelog names every change in each release.

Guides

  • Get started: configure the provider and apply a first project, database, application, and domain.
  • Usage examples: short, complete configurations for the common setups: an app from GitLab with Slack alerts, a worker server, private images, a teammate with limited access, nightly backups, variables as a map, a highly available application with Swarm settings, a full stack, the Dokploy host backup, connection checks, and lookups.
  • Adopt an existing Dokploy server: import a running server into the state without a rebuild.
  • Deploy semantics: deploy_on_change, deployment_timeout, deploy failures, and Swarm changes.
  • Secrets and sensitive values: environment variables, database passwords, backup credentials, and the write-only companions that keep a secret out of the state.
  • Upgrade guide: what each release needs from your configuration. v1.8 has nothing breaking; v1.0 has no change; v0.13 adds the coverage of this page; v0.12 adds the write-only companions; v0.11 had the breaking changes.
  • Changelog: every release, newest first, with the attributes it added, changed, or fixed.

Before you start

These three problems cause the most failures:

  1. Dokploy rate-limits API keys, and an exhausted key returns 401, not 429. A large apply can fail with an authentication error on a key that works for single requests. See Get started.
  2. dokploy_application and dokploy_compose own the whole service. An apply of either resource replaces each setting that changed in the Dokploy UI. Manage a service in Terraform or in the UI, not in both. See Adopt an existing Dokploy server.
  3. The default docker_image for MariaDB and MongoDB does not exist on Docker Hub. Set an explicit tag, or each deploy fails. See Deploy semantics.

Example Usage

terraform
provider "dokploy" {
  # If endpoint is unset, the provider reads the DOKPLOY_ENDPOINT environment
  # variable. If api_key is unset, it reads DOKPLOY_API_KEY.
  endpoint = "https://dokploy.example.com"

  # Set insecure = true only for a server with a self-signed certificate.
}

Schema

Optional

  • api_key (String, Sensitive) Dokploy API key. The provider sends it as the x-api-key header. If unset, the provider reads the DOKPLOY_API_KEY environment variable.
  • endpoint (String) Base URL of the Dokploy server, for example https://dokploy.example.com. If unset, the provider reads the DOKPLOY_ENDPOINT environment variable.
  • insecure (Boolean) Skip the TLS certificate verification, for self-signed endpoints. Defaults to false.