Skip to content
Install

Manage Orchard with Terraform and OpenTofu

The hackclub/orchard provider lets you describe Orchard projects, apps, databases, and jobs in HCL and keep them in version control, instead of creating them by hand in the dashboard. One binary serves both Terraform and OpenTofu, and it uses the same API client as the orchard CLI.

  • An Orchard instance.
  • An API token or a saved sign-in from orchard auth login.
  • Terraform or OpenTofu.
  • Go, to build the provider locally.

The provider is not yet on a public registry. To use it, build it and point your client at the build.

  1. Build the provider:

    cd apps/cli && go build -o terraform-provider-orchard ./tofu-provider
  2. Add a development override to ~/.terraformrc or ~/.tofurc:

    provider_installation {
    dev_overrides {
    "hackclub/orchard" = "/absolute/path/to/apps/cli"
    }
    direct {}
    }

With a development override, you do not run init. plan, apply, and destroy work as usual.

terraform {
required_providers {
orchard = {
source = "hackclub/orchard"
}
}
}
provider "orchard" {}

The provider reads the instance URL and token from these places, in order:

  1. The api_url and token attributes on the provider block.
  2. The ORCHARD_API_URL and ORCHARD_API_TOKEN environment variables.
  3. The token saved by orchard auth login.

In CI, set the two environment variables.

The following configuration creates a project with a database, an app, a variable, a domain, and a scheduled job.

resource "orchard_project" "midnight" {
organization_id = var.organization_id
name = "Midnight"
}
resource "orchard_database" "db" {
project_id = orchard_project.midnight.id
name = "midnight"
}
resource "orchard_deployment" "web" {
project_id = orchard_project.midnight.id
name = "web"
image = "ghcr.io/example/midnight-web:1.4.0"
port = 3000
replicas = 2
}
resource "orchard_env_var" "database_url" {
deployment_id = orchard_deployment.web.id
key = "DATABASE_URL"
value = "$${{resource.midnight.connection_string}}"
}
resource "orchard_ingress" "www" {
project_id = orchard_project.midnight.id
deployment_id = orchard_deployment.web.id
host = "midnight.example.com"
}
resource "orchard_job" "nightly" {
project_id = orchard_project.midnight.id
name = "nightly-report"
schedule = "0 3 * * *"
steps {
name = "report"
image = "ghcr.io/example/midnight-report:1.0.0"
command = "node report.js"
}
}

The DATABASE_URL value is a reference that Orchard resolves when the pod starts. The password does not appear in state.

Resource Manages Replaced when these change
orchard_project A project in an organization organization_id, slug
orchard_deployment An app that runs a container image. Image and replica changes roll the app in place. project_id, environment_id, name, port, start_command
orchard_database A managed Postgres database. Exposes host, port, database_name, and status. Does not expose the password. Every attribute
orchard_ingress A custom domain routed to an app project_id, deployment_id
orchard_env_var One variable on an app. Other variables stay as they are. A secret value is write-only. deployment_id, key
orchard_job A scheduled or on-demand job made of image steps project_id

The provider creates only image-based apps. To create an app from a repository, use the dashboard or orchard deploy create --github. The provider can then read that app and set its variables.

Each resource supports import. IDs are the Orchard IDs in URLs. Two resources use composite IDs:

tofu import orchard_env_var.database_url <deployment id>:DATABASE_URL
tofu import orchard_ingress.www <project id>:<ingress id>