# terraform-provider-dokploy

> Terraform provider for the Dokploy PaaS: projects, environments, services with Docker Swarm settings, databases, domains, backups, servers, git providers, notifications, users, and API keys.

- status: maintained
- language: Go
- version: v1.8.0
- license: MIT
- registry: vanillauys/dokploy
- repo: https://github.com/vanillauys/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

```hcl
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](/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](/docs/dokploy/guides/getting-started),
  [usage examples](/docs/dokploy/guides/usage-examples),
  [upgrade guide](/docs/dokploy/guides/upgrading),
  [adopting an existing instance](/docs/dokploy/guides/adopting-an-existing-instance),
  [deploy semantics](/docs/dokploy/guides/deploy-semantics), and
  [secrets](/docs/dokploy/guides/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](https://github.com/vanillauys/terraform-provider-dokploy).