terraform-provider-dokploy

Dokploy is a self-hosted PaaS. This provider manages it with Terraform: projects and environments, applications and compose stacks from GitHub, GitLab, Bitbucket, Gitea, git, or an image, six database engines, domains and TLS certificates, mounts, backups, schedules, networks, remote servers and SSH keys, registries, twelve notification channels, vault providers, users, permissions, and API keys: 48 resources and 45 data sources. Docker Swarm settings (replicas, placement, rolling updates, health checks) apply to applications and databases, a backup covers the Dokploy host itself, and verify_connection tests a credential during the apply. It works with Terraform 1.5 or later and with OpenTofu. The write-only secret attributes need Terraform 1.11 or later.

CI runs the acceptance suite against a real Dokploy instance on every PR and every night. The stack behind this site is declared through this provider, so every release runs in production here.

Usage

terraform {
  required_providers {
    dokploy = {
      source  = "vanillauys/dokploy"
      version = "~> 1.8"
    }
  }
}

provider "dokploy" {
  endpoint = "https://dokploy.example.com"
  # api_key falls back to the DOKPLOY_API_KEY environment variable
}

resource "dokploy_project" "main" {
  name = "wihan-dev"
}

resource "dokploy_application" "web" {
  name           = "web"
  environment_id = dokploy_project.main.production_environment_id

  docker = {
    image = "ghcr.io/example/web:1.0.0"
  }
}

The full reference is at /docs/dokploy: every resource, data source, and guide.

For agents

• Install from the Terraform registry: source vanillauys/dokploy. Pin the minor version, ~> 1.8. The provider follows semantic versioning from v1.0.0: a minor release adds resources and attributes and never changes what an existing attribute does.
• Configure endpoint and api_key, or set the DOKPLOY_ENDPOINT and DOKPLOY_API_KEY environment variables.
• Read the reference at https://wihan.dev/docs/dokploy. Append .md to any docs URL for raw markdown, for example https://wihan.dev/docs/dokploy/resources/application.md.
• Read the guides first: get started, usage examples, upgrade guide, adopting an existing instance, deploy semantics, and secrets.
• Use dokploy_project.<name>.production_environment_id for the default environment. A for expression over environments becomes unknown on every project update and forces a replacement of the service.
• Every secret attribute has a write-only pair, <name>_wo and <name>_wo_version. Set one of the two, not both. Rotate the secret with a version bump; the state then holds no secret.
• Scale a service with swarm.mode.replicated.replicas, or with the top-level replicas, never both: the provider rejects the pair at plan time. A swarm change reaches the service at the next deploy.
• verify_connection = true calls the Dokploy test endpoint of a registry, destination, AI endpoint, git provider, or notification during the apply. A notification test sends a real message.
• Known traps: an exhausted API-key rate limit returns 401, not 429; dokploy_application and dokploy_compose own the whole service, so manage a service in Terraform or in the UI, not both; dokploy_environment_variables owns the whole env of its target, so put ignore_changes = [env] on the target.
• Source and issues: github.com/vanillauys/terraform-provider-dokploy.