Terraform Provider for Dokku

🚀 Manage your Dokku applications and services using Terraform!

Key Features • How To Use • Developing • Full Example • Terraform Registry

This is a terraform provider for provisioning apps on Dokku installations. Not all configuration options are currently supported.

This provider is currently tested against Dokku >= v0.30 and <= 0.36, although can be forced to run against any version. Read more.

Key Features

📦 Apps: Create and manage Dokku applications
🗄️ Databases: Provision PostgreSQL, MySQL, and Redis services
🔗 Service Links: Connect your apps to databases
🌐 Domains: Configure custom domains for your apps
🔧 Config: Manage environment variables and app settings

How To Use

Add the provider to your terraform block

terraform {
  required_providers {
    dokku = {
      source  = "aaronstillwell/dokku"
      version = "> 0.5"
    }
  }
}

Initialise the provider with your host settings. The SSH key should be that of a dokku user. Dokku users have dokku set as a forced command - the provider will not attempt to explicitly specify the dokku binary over SSH.

An SSH key can be provided as an absolute path or inline.

provider "dokku" {
  ssh_host = "dokku.me"
  ssh_user = "dokku"
  ssh_port = 8022
  ssh_cert = "/home/user/.ssh/dokku-cert" # can also provide an SSH key directly as a string
  ssh_passphrase = "this is optional"
  # skipknownhosts_check = true
}

Declare resources. See examples for more info.

resource "dokku_app" "rails-app" {
  name = "rails-app"
config_vars = {     AWS_REGION                 = "eu-west-2"     S3DATABUCKET             = "app-data-source"     ACTIVESTORAGEBUCKET_NAME = "active-storage"   }
domains = [     "test-2.dokku.me"   ]
buildpacks = [     "https://github.com/heroku/heroku-buildpack-nodejs.git",     "https://github.com/heroku/heroku-buildpack-ruby.git"   ] }

Tested dokku versions

The provider is currently tested against versions 0.30 through to 0.35 of dokku. Moving forward, it's likely the number of dokku versions being tested will change, with older versions being dropped as newer ones become available.

The provider will check the version of dokku being used and by default will fail if a version outside this range is detected. This behaviour can be disabled with the failonuntested_version attribute. E.g

provider "dokku" {
  ssh_host = "dokku.me"
  ssh_user = "dokku"
  ssh_port = 8022
  ssh_cert = "/home/user/.ssh/dokku-cert"
  
  # Tell the provider not to fail if a dokku version is detected that hasn't
  # been tested against the current version of the provider.
  failonuntested_version = false
}

Developing

The easiest way to develop this provider further is to set up a vagrant box with the provided vagrantfile.

Run vagrant up. This will create an ubuntu VM with the prerequisites needed to develop the provider.
SSH into the VM with vagrant ssh
Navigate to where the source is mounted in the VM cd /vagrant

From here you can build & test the provider. This VM has dokku running in a docker container, which can be SSH'd into from the VM like any other dokku install.

Please raise an issue if you have any difficulties developing.

Run acceptance tests locally

You can run the full acceptance test suite locally with make testacc, but note these take some time to run (~10 min).

It may be preferrable to run only the test you're working on, with e.g TF_ACC=1 go test terraform-provider-dokku/internal/provider -v -run TestSetAppConfigVars

Manual testing with a terraform config

The examples directory can be used for ad-hoc testing configs manually.

Navigate to the examples dir while over SSH into the vagrant vm cd /vagrant/examples/
Build the provider for use locally with ./build.sh
You can then use the terraform files in examples and run them against the local dokku instance with terraform apply.

Full Example

See also examples/main.tf for a commented example.

terraform {
  required_providers {
    dokku = {
      source  = "aaronstillwell/dokku"
    }
  }
}
provider "dokku" {   ssh_host = "dokku.me"   ssh_user = "dokku"   ssh_port = 8022   ssh_cert = "/home/users/.ssh/dokku-cert" }
Create an app...
resource "dokku_app" "rails-app" {
  name = "rails-app"
config_vars = {     AWS_REGION                 = "eu-west-2"     S3DATABUCKET             = "app-data-source"     ACTIVESTORAGEBUCKET_NAME = "active-storage"   }
domains = [     "test-2.dokku.me"   ]
buildpacks = [     "https://github.com/heroku/heroku-buildpack-nodejs.git",     "https://github.com/heroku/heroku-buildpack-ruby.git"   ] }
Create accompanying services...
resource "dokkupostgresservice" "rails-postgres" {
  name          = "rails-postgres"
  image_version = "11.12"
}
resource "dokkuredisservice" "rails-redis" {   name          = "rails-redis" }
Link the services to the app...
resource "dokkupostgresservice_link" "rails-postgres-link" {
  app     = dokku_app.rails-app.name
  service = dokkupostgresservice.rails-postgres.name
alias = "TESTDBURL"   # query_string = "" }
resource "dokkuredisservice_link" "rails-redis-link" {   app     = dokku_app.rails-app.name   service = dokkuredisservice.rails-redis.name
alias = "TESTREDISURL"   # query_string = "" }

🔗 More in this category