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

dokploy_application (Resource)

An application service in a Dokploy environment. One resource manages the source, the build settings, and the environment variables.

~> Terraform owns the whole application. An apply of this resource rewrites the source, build, and environment configuration of the application. The next apply therefore replaces each of those settings that changed in the Dokploy UI. Manage an application in Terraform or in the UI, not in both.

Example Usage

terraform
resource "dokploy_application" "example" {
  name           = "web"
  environment_id = dokploy_project.example.production_environment_id

  docker = {
    image = "traefik/whoami:v1.10"
  }

  env = <<-EOT
    PORT=80
  EOT

  # Attach the application to more Docker networks. The attachment applies on
  # the next deploy. Replace the placeholder with a network id from your own
  # server before you uncomment the line.
  # network_ids = ["<dokploy-network-id>"]
}

# Preview deployments for each pull request of a GitHub source, a rollback
# image per deploy, and a build on a separate build server.
resource "dokploy_application" "with_previews" {
  name           = "web"
  environment_id = dokploy_project.example.production_environment_id
  title          = "wihan.dev"
  subtitle       = "Astro site"

  github = {
    owner      = "vanillauys"
    repository = "wihan-dev-app"
    branch     = "master"
    github_id  = data.dokploy_github_provider.main.id
  }

  preview_deployments = {
    enabled  = true
    limit    = 3
    port     = 4321
    https    = true
    wildcard = "*.preview.example.com"
  }

  rollback = {
    enabled = true
  }

  build_server_id = dokploy_server.build.id
  clean_cache     = true
}

# From a GitLab project. The provider record holds the OAuth application;
# project_id and path_namespace come from the project's settings page.
resource "dokploy_application" "from_gitlab" {
  name           = "api"
  environment_id = dokploy_project.example.production_environment_id

  gitlab = {
    gitlab_id      = dokploy_gitlab_provider.main.id
    owner          = "my-group"
    repository     = "api"
    branch         = "main"
    project_id     = 12345678
    path_namespace = "my-group/api"
  }

  build = {
    type = "nixpacks"
  }
}

# From a Bitbucket repository. repository_slug is the last part of the
# repository URL.
resource "dokploy_application" "from_bitbucket" {
  name           = "worker"
  environment_id = dokploy_project.example.production_environment_id

  bitbucket = {
    bitbucket_id    = dokploy_bitbucket_provider.main.id
    owner           = "acme"
    repository      = "Worker"
    repository_slug = "worker"
    branch          = "main"
  }
}

# From a Gitea repository, built from a subdirectory.
resource "dokploy_application" "from_gitea" {
  name           = "docs"
  environment_id = dokploy_project.example.production_environment_id

  gitea = {
    gitea_id   = dokploy_gitea_provider.main.id
    owner      = "acme"
    repository = "monorepo"
    branch     = "main"
    build_path = "/docs"
  }
}

# Run two tasks with a rolling update policy and a placement constraint. The
# swarm block replaces the top-level replicas attribute: set swarm.mode or
# replicas, not both. Durations are in nanoseconds.
resource "dokploy_application" "swarm" {
  name           = "api"
  environment_id = dokploy_project.example.production_environment_id

  docker = {
    image = "traefik/whoami:v1.10"
  }

  swarm = {
    mode = { replicated = { replicas = 2 } }

    placement = {
      constraints = ["node.role == manager"]
    }

    update_config = {
      parallelism = 1
      order       = "start-first"
    }

    stop_grace_period = 10000000000 # 10 seconds
  }
}
terraform
# A highly available service. Swarm runs two tasks, starts each new task
# before it stops the old one, and restarts a task that fails the health check.
# Set swarm.mode or replicas. The provider rejects a plan that sets both.
# Durations are in nanoseconds.
resource "dokploy_application" "ha" {
  name           = "api"
  environment_id = dokploy_project.example.production_environment_id

  docker = {
    image = "traefik/whoami:v1.10"
  }

  swarm = {
    mode = {
      replicated = {
        replicas = 2
      }
    }

    update_config = {
      parallelism = 1
      delay       = 10000000000 # 10 seconds
      order       = "start-first"
    }

    health_check = {
      test         = ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:80/health"]
      interval     = 10000000000 # 10 seconds
      timeout      = 3000000000  # 3 seconds
      retries      = 3
      start_period = 5000000000 # 5 seconds
    }
  }
}

Schema

Required

  • environment_id (String) Id of the environment that holds this application. Use dokploy_project.production_environment_id for the default environment.
  • name (String) Display name of the application.

Optional

  • app_name (String) Internal Dokploy app name, <app_name_prefix>-<suffix>. The server generates it at create. You cannot set it; set app_name_prefix instead.
  • app_name_prefix (String) Prefix of the Dokploy app name. Dokploy appends -<suffix> (six random lowercase characters) at create and never changes the app name afterwards. Defaults to name. Use lowercase letters, digits, dots, underscores, and hyphens; 56 characters at most. A change replaces the resource. After an import the provider derives the value from app_name.
  • args (List of String) Arguments for the container command.
  • auto_deploy (Boolean) Redeploy automatically when Dokploy receives a webhook for the configured branch or tag.
  • bitbucket (Attributes) Bitbucket source, through a dokploy_bitbucket_provider. Set exactly one of github, gitlab, bitbucket, gitea, git, or docker. (see nested schema for bitbucket)
  • build (Attributes) Build settings. The server default is nixpacks. (see nested schema for build)
  • build_args (String) Build-time arguments in the same multiline format.
  • build_registry_id (String) Id of the dokploy_registry through which a build server hands the image to the application server. Omit it for the local Docker image store.
  • build_secrets (String, Sensitive) Build-time secrets in the same multiline KEY=value format. Docker mounts them during the build and does not store them in the image. If you omit this attribute, the provider clears any value from the Dokploy UI. An omitted value and "" read back the same, so omit the attribute to clear it.
  • build_server_id (String) Id of the dokploy_server with server_type = "build" that builds the image. Omit it to build on the server that runs the application.
  • clean_cache (Boolean) Build without the Docker layer cache. Defaults to false.
  • command (String) Override the container entrypoint command.
  • cpu_limit (String) Hard CPU limit in nano-CPUs, as a whole number in a string: "1000000000" is one CPU, "500000000" half a CPU. Dokploy reads the value with parseInt, so a Docker-style suffix such as 512m deploys as 512 bytes and a fraction such as 0.5 sets no limit. Use a whole number.
  • cpu_reservation (String) Reserved CPU in nano-CPUs, as a whole number in a string: "250000000" is a quarter CPU. Dokploy reads the value with parseInt, so a Docker-style suffix such as 512m deploys as 512 bytes and a fraction such as 0.5 sets no limit. Use a whole number.
  • create_env_file (Boolean) Write the environment variables to a .env file in the build context. Defaults to true, the Dokploy default for a new application.
  • deploy_on_change (Boolean) Deploy after a create, and after a change to an attribute that starts a deploy. Defaults to true.
  • deployment_timeout (String) The maximum wait for a deploy to reach a terminal status, as a Go duration string. Defaults to "15m". On timeout, the apply fails, but the deploy continues on the server.
  • description (String) Free-form description.
  • detach_dokploy_network (Boolean) Detach the shared dokploy-network from this application. Defaults to false. It has an effect only together with network_ids, and it applies on the next deploy.
  • docker (Attributes) Docker image source. (see nested schema for docker)
  • drop_build_path (String) Path inside the container where Dokploy drops the uploaded build archive, for the drag-and-drop source of the UI. Omit it for the Dokploy default.
  • enable_submodules (Boolean) Check out git submodules with the clone. Applies to the github and git sources. Dokploy ignores it for docker.
  • env (String) Environment variables in the native Dokploy multiline KEY=value format. Use Terraform sensitive variables for secret values. The provider writes build_secrets in the same request, so an omitted build_secrets clears the value on the server. Set build_secrets explicitly to keep it.
  • git (Attributes) Plain git source: any repository that the server can reach over HTTPS or SSH. Set exactly one of github, gitlab, bitbucket, gitea, git, or docker. (see nested schema for git)
  • gitea (Attributes) Gitea source, through a dokploy_gitea_provider. Set exactly one of github, gitlab, bitbucket, gitea, git, or docker. The provider must be authorized in the Dokploy UI before a deploy can clone from it. (see nested schema for gitea)
  • github (Attributes) GitHub App source. Set exactly one of github, gitlab, bitbucket, gitea, git, or docker. Configure the GitHub provider (github_id) in Dokploy under Git > GitHub before you use this block. (see nested schema for github)
  • gitlab (Attributes) GitLab source, through a dokploy_gitlab_provider. Set exactly one of github, gitlab, bitbucket, gitea, git, or docker. The provider must be authorized in the Dokploy UI before a deploy can clone from it. (see nested schema for gitlab)
  • memory_limit (String) Hard memory limit in bytes, as a whole number in a string: "536870912" is 512 MiB. Dokploy reads the value with parseInt, so a Docker-style suffix such as 512m deploys as 512 bytes and a fraction such as 0.5 sets no limit. Use a whole number.
  • memory_reservation (String) Reserved memory in bytes, as a whole number in a string: "268435456" is 256 MiB. Dokploy reads the value with parseInt, so a Docker-style suffix such as 512m deploys as 512 bytes and a fraction such as 0.5 sets no limit. Use a whole number.
  • network_ids (Set of String) Ids of the Dokploy network records to attach this application to. The attachment applies on the next deploy. Omit it to keep only the default dokploy-network. An empty set is not valid. Omit the attribute instead.
  • preview_deployments (Attributes) Preview deployments: Dokploy deploys each pull request of a GitHub source to its own URL under wildcard. The block holds the settings; the preview deployment records themselves are imperative, and this provider does not manage them. Omit the block to write the Dokploy defaults, which keep previews off. (see nested schema for preview_deployments)
  • registry_id (String) Id of the Dokploy registry that receives the built images. Use the id of a dokploy_registry resource.
  • replicas (Number) Number of container replicas. The Dokploy schema has no null variant for this field, so it always has a value. If swarm.mode is set, Dokploy uses the mode and ignores this attribute. Set replicas or swarm.mode, not both: the provider rejects the pair at plan time.
  • rollback (Attributes) Rollback settings: Dokploy keeps the image of each successful deploy, so that the UI can roll the application back to it. The rollback itself is imperative, and this provider does not manage it. Omit the block to write the Dokploy defaults, which keep rollbacks off. (see nested schema for rollback)
  • server_id (String) Id of the remote server that runs the application. Defaults to the Dokploy host.
  • subtitle (String) Display subtitle in the Dokploy UI.
  • swarm (Attributes) The Docker Swarm service specification. Each attribute maps to one Dokploy column and keeps the Docker field names in snake case. Omit the block to write null to every column. A change starts a redeploy when deploy_on_change is true. (see nested schema for swarm)
  • title (String) Display title in the Dokploy UI. Omit it to show the name.
  • watch_paths (List of String) Glob paths that start an auto-deploy when they change. Applies to the github and git sources. Dokploy ignores it for docker. If you omit it, the provider clears any value from the Dokploy UI.

Read-Only

  • created_at (String) Creation timestamp from the server.
  • id (String) Application id.
  • status (String) Application status from Dokploy.

Nested Schema for bitbucket

Required:

  • bitbucket_id (String) Id of the Bitbucket provider in Dokploy: dokploy_bitbucket_provider.id or the data source’s id.
  • branch (String) Branch to deploy.
  • owner (String) Workspace or user that owns the repository.
  • repository (String) Repository name.
  • repository_slug (String) Repository slug, the last part of the repository URL. It usually equals the repository name in lowercase.

Optional:

  • build_path (String) Path inside the repository to build from.

Nested Schema for build

Required:

  • type (String) Build type: one of nixpacks, dockerfile, heroku_buildpacks, paketo_buildpacks, static, railpack. heroku_buildpacks and railpack take a builder version: set heroku_version or railpack_version. If you omit the version attribute, the server applies its default builder version, and each apply resets any version from the Dokploy UI.

Optional:

  • build_stage (String) Target stage for multi-stage builds.
  • context_path (String) Docker build context path, relative to the repository root. If you leave it unset, Dokploy v0.30.6 and later build from the directory that holds the Dockerfile. Dokploy v0.30.5 and earlier build from the repository root. Set it to . to keep the repository root as the context on every release.
  • dockerfile (String) Dockerfile path, for build type dockerfile.
  • heroku_version (String) Builder version for build type heroku_buildpacks. Omit it to use the server default.
  • is_static_spa (Boolean) Serve the build output as a single-page application. Unknown paths go to the index document.
  • publish_directory (String) Publish directory, for build type static.
  • railpack_version (String) Builder version for build type railpack. Omit it to use the server default.

Nested Schema for docker

Required:

  • image (String) Image reference, for example nginx:1.27.

Optional:

  • password (String, Sensitive) Registry password for private images.
  • registry_url (String) Registry URL for private registries.
  • username (String) Registry username for private images.

Nested Schema for git

Required:

  • branch (String) Branch to deploy.
  • url (String) Clone URL.

Optional:

  • build_path (String) Path inside the repository to build from.
  • ssh_key_id (String) Id of a Dokploy SSH key, for private repositories.

Nested Schema for gitea

Required:

  • branch (String) Branch to deploy.
  • gitea_id (String) Id of the Gitea provider in Dokploy: dokploy_gitea_provider.id or the data source’s id.
  • owner (String) Owner of the repository: a user or an organization.
  • repository (String) Repository name.

Optional:

  • build_path (String) Path inside the repository to build from.

Nested Schema for github

Required:

  • branch (String) Branch to deploy.
  • github_id (String) Id of the GitHub provider in Dokploy.
  • owner (String) Repository owner: a user or an organization.
  • repository (String) Repository name.

Optional:

  • build_path (String) Path inside the repository to build from.
  • trigger_type (String) The git event that starts an auto-deploy: push or tag. Dokploy writes this field on each source save, whether or not the request carries it. The field therefore always has a value, and Terraform must manage it.

Nested Schema for gitlab

Required:

  • branch (String) Branch to deploy.
  • gitlab_id (String) Id of the GitLab provider in Dokploy: dokploy_gitlab_provider.id or the data source’s id.
  • owner (String) Owner of the project: a user or a group.
  • path_namespace (String) Full path of the project, for example my-group/my-project. GitLab addresses a project by it.
  • project_id (Number) Numeric GitLab project id, shown on the project’s settings page.
  • repository (String) Project name.

Optional:

  • build_path (String) Path inside the repository to build from.

Nested Schema for preview_deployments

Optional:

  • build_args (String) Build-time arguments for the preview deployments, in the same multiline format.
  • build_secrets (String, Sensitive) Build-time secrets for the preview deployments, in the same multiline format. Set this attribute or build_secrets_wo. If you omit both, the provider clears any value from the Dokploy UI.
  • build_secrets_wo (String, Sensitive, Write-only) Write-only form of build_secrets. Terraform keeps it out of the plan and the state. It needs Terraform 1.11 or later. Do not set it together with build_secrets. The server does not return the value, so every update sends it. Change build_secrets_wo_version to start an update when only this value changed.
  • build_secrets_wo_version (Number) Version of build_secrets_wo. Change it to start an update when only build_secrets_wo changed. It needs build_secrets_wo.
  • certificate_type (String) Certificate strategy for the preview domains: letsencrypt, none, or custom. Defaults to "none".
  • custom_cert_resolver (String) Traefik certificate resolver name, for certificate_type = "custom".
  • enabled (Boolean) Create a preview deployment for each pull request. Defaults to false.
  • env (String) Environment variables for the preview deployments, in the native Dokploy multiline KEY=value format.
  • https (Boolean) Serve the preview domains over HTTPS. Defaults to false.
  • labels (List of String) Docker labels for the preview containers, as key=value strings. An empty list is not valid. Omit the attribute instead.
  • limit (Number) Maximum number of preview deployments that exist at once. Defaults to 3.
  • path (String) External path that the preview domains match. Defaults to "/".
  • port (Number) Container port that the preview domains forward to. Defaults to 3000.
  • require_collaborator_permissions (Boolean) Deploy a preview only for pull requests from repository collaborators. Defaults to true.
  • wildcard (String) Wildcard host for the preview domains, for example *.preview.example.com. Dokploy generates one host per pull request under it.

Nested Schema for rollback

Optional:

  • enabled (Boolean) Keep the image of each successful deploy for a rollback. Defaults to false.
  • registry_id (String) Id of the dokploy_registry that stores the rollback images. Omit it for the local Docker image store.

Nested Schema for swarm

Optional:

Nested Schema for swarm.endpoint_spec

Optional:

Nested Schema for swarm.endpoint_spec.ports

Optional:

  • protocol (String) Protocol: tcp, udp, or sctp.
  • publish_mode (String) Publish mode: ingress or host.
  • published_port (Number) Port on the host or on the routing mesh.
  • target_port (Number) Port in the container.

Nested Schema for swarm.health_check

Optional:

  • interval (Number) Time between two checks, in nanoseconds.
  • retries (Number) Number of failed checks after which the container is unhealthy.
  • start_period (Number) Time after the start in which a failed check does not count, in nanoseconds.
  • test (List of String) The check command, for example ["CMD", "curl", "-f", "http://localhost"].
  • timeout (Number) Time after which a check fails, in nanoseconds.

Nested Schema for swarm.mode

Optional:

Nested Schema for swarm.mode.global

Nested Schema for swarm.mode.global_job

Nested Schema for swarm.mode.replicated

Optional:

  • replicas (Number) Number of tasks.

Nested Schema for swarm.mode.replicated_job

Optional:

  • max_concurrent (Number) Maximum number of tasks that run at the same time.
  • total_completions (Number) Number of tasks that must complete.

Nested Schema for swarm.network

Optional:

  • aliases (List of String) Network aliases of the service.
  • driver_opts (Map of String) Driver options of the network attachment.
  • target (String) Name or ID of the network.

Nested Schema for swarm.placement

Optional:

Nested Schema for swarm.placement.platforms

Required:

  • architecture (String) The CPU architecture, for example amd64.
  • os (String) The operating system, for example linux.

Nested Schema for swarm.placement.preferences

Required:

Nested Schema for swarm.placement.preferences.spread

Required:

  • spread_descriptor (String) The node label to spread over, for example node.labels.zone.

Nested Schema for swarm.restart_policy

Optional:

  • condition (String) Condition to restart a task: none, on-failure, or any.
  • delay (Number) Time between two restarts, in nanoseconds.
  • max_attempts (Number) Number of restarts before Swarm stops the attempts.
  • window (Number) Time to wait before Swarm decides that a restart worked, in nanoseconds.

Nested Schema for swarm.rollback_config

Required:

  • order (String) Order of the tasks: start-first or stop-first.
  • parallelism (Number) Number of tasks that roll back at the same time. The value 0 means all tasks at once.

Optional:

  • delay (Number) Time between two batches, in nanoseconds.
  • failure_action (String) Action if a task fails: continue, pause, or rollback.
  • max_failure_ratio (Number) Fraction of failed tasks that the service tolerates, from 0 to 1.
  • monitor (Number) Time to watch each task for a failure after it starts, in nanoseconds.

Nested Schema for swarm.ulimits

Required:

  • hard (Number) The hard limit.
  • name (String) Name of the limit, for example nofile.
  • soft (Number) The soft limit.

Nested Schema for swarm.update_config

Required:

  • order (String) Order of the tasks: start-first or stop-first.
  • parallelism (Number) Number of tasks that update at the same time. The value 0 means all tasks at once.

Optional:

  • delay (Number) Time between two batches, in nanoseconds.
  • failure_action (String) Action if a task fails: continue, pause, or rollback.
  • max_failure_ratio (Number) Fraction of failed tasks that the service tolerates, from 0 to 1.
  • monitor (Number) Time to watch each task for a failure after it starts, in nanoseconds.

Import

Import is supported using the following syntax:

In Terraform v1.5.0 and later, the import block can be used with the id attribute, for example:

terraform
import {
  to = dokploy_application.example
  id = "V1StGXR8_Z5jdHi6B-myT"
}

The terraform import command can be used, for example:

shell
terraform import dokploy_application.example V1StGXR8_Z5jdHi6B-myT