Terraform Provider for Dokku (Terraform Plugin Framework)

This repository is a Terraform provider for Dokku.

For now only subset of dokku features are supported now.

Using the provider

1. Set up dokku or Upgrade dokku on installations with prebuilt dokku (like on DigitalOcean)

2. Set up SSH keys

# ON LOCAL PC
# Set up publickey auth
ssh-copy-id user@IP

# ON VPS
# Add key to dokku
# You can change "admin" to any preferred username, describing who you are related to this server instance
cat ~/.ssh/authorized_keys | dokku ssh-keys:add admin

3. Add the provider and host settings to your terraform block. The SSH key must belong to dokku user. Dokku users have set dokku as a forced command - the provider will not attempt to explicitly specify the dokku binary over SSH.

terraform {
  required_providers {
    dokku = {
      source  = "registry.terraform.io/aliksend/dokku"
    }
  }
}

provider "dokku" {
  ssh_host = "dokku.me"

  # optional
  ssh_user = "dokku"
  ssh_port = 22
  ssh_cert = "~/.ssh/id_rsa"
}

Documentation

Deploy using push from git repository (simplest way)

This configuration will create your infrastructure using terraform and then deploy using git push.

Example .gitlab-ci.yml

stages:
  - terraform
  - deploy

variables:
  SSH_HOST: __YOUR_HOST__
  APP_NAME: __YOUR_APP__
  TF_STATE_ADDRESS: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/main"

terraform:
  image:
    name: hashicorp/terraform:light
    entrypoint: ['']
  stage: terraform
  only:
    - master
  script:
    - terraform version
    - terraform init
      -reconfigure
      -backend-config="address=${TF_STATE_ADDRESS}"
      -backend-config="lock_address=${TF_STATE_ADDRESS}/lock"
      -backend-config="unlock_address=${TF_STATE_ADDRESS}/lock"
      -backend-config="username=gitlab-ci-token"
      -backend-config="password=$CI_JOB_TOKEN"
      -backend-config="lock_method=POST"
      -backend-config="unlock_method=DELETE"
      -backend-config="retry_wait_min=5"
    - terraform apply
      -input=false
      -auto-approve
      -var ssh_cert="$SSH_PRIVATE_KEY"

dokku_deploy:
  image: ilyasemenov/gitlab-ci-git-push
  stage: deploy
  only:
    - master
  script:
    - git-push ssh://dokku@$SSH_HOST/$APP_NAME

You need to have gitlab variable SSH_PRIVATE_KEY with private key, added in step two.

Example terraform configuration

variable "ssh_cert" {
  type = string
  description = "SSH cert"
}

terraform {
  required_providers {
    dokku = {
      source = "registry.terraform.io/aliksend/dokku"
    }
  }

  backend "http" {}
}

provider "dokku" {
  ...
  ssh_cert = var.ssh_cert
}

resource "dokku_app" "appname" {
  ...

  deploy = null
}

Deploy using sync with git repository

This configuration will create your infrastructure using terraform and set up dokku deployment using sync with git repository.

Example .gitlab-ci.yml

stages:
  - deploy

variables:
  TF_STATE_ADDRESS: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/main"

dokku_deploy:
  image:
    name: hashicorp/terraform:light
    entrypoint: ['']
  stage: deploy
  only:
    - master
  script:
    - terraform version
    - terraform init
      -reconfigure
      -backend-config="address=${TF_STATE_ADDRESS}"
      -backend-config="lock_address=${TF_STATE_ADDRESS}/lock"
      -backend-config="unlock_address=${TF_STATE_ADDRESS}/lock"
      -backend-config="username=gitlab-ci-token"
      -backend-config="password=$CI_JOB_TOKEN"
      -backend-config="lock_method=POST"
      -backend-config="unlock_method=DELETE"
      -backend-config="retry_wait_min=5"
    - terraform apply
      -input=false
      -auto-approve
      -var ssh_cert="$SSH_PRIVATE_KEY"
      -var git_repository="$CI_REPOSITORY_URL"
      -var git_repository_ref="$CI_COMMIT_SHA"

You need to have gitlab variable SSH_PRIVATE_KEY with private key, added in step two.

As long as built-in gitlab built-in env var CI_REPOSITORY_URL contains credentials you don't need to provide it explicitly.

Example terraform configuration

variable "ssh_cert" {
  type = string
  description = "SSH cert"
}

variable "git_repository" {
  type = string
  description = "Git repository to sync with"
}

variable "git_repository_ref" {
  type = string
  description = "Ref in git repository to sync with"
}

terraform {
  required_providers {
    dokku = {
      source = "registry.terraform.io/aliksend/dokku"
    }
  }

  backend "http" {}
}

provider "dokku" {
  ...
  ssh_cert = var.ssh_cert
}

resource "dokku_app" "appname" {
  ...

  deploy = {
    type = "git_repository"
    git_repository = var.git_repository
    git_repository_ref = var.git_repository_ref
  }
}

Deploy using docker image

This configuration will create your infrastructure using terraform and set up dokku docker image deployment.

Example .gitlabci.yml

stages:
  - build
  - deploy

variables:
  TF_STATE_ADDRESS: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/main"

build:
  image: docker:stable
  stage: build
  services:
    - docker:dind
  only:
    - master
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_DRIVER: overlay2
  script:
    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.gitlab.com
    - docker pull $CI_REGISTRY_IMAGE:latest || true
    - docker build --cache-from $CI_REGISTRY_IMAGE:latest --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - docker push $CI_REGISTRY_IMAGE:latest

dokku_deploy:
  image:
    name: hashicorp/terraform:light
    entrypoint: ['']
  stage: deploy
  only:
    - master
  script:
    - terraform version
    - terraform init
      -reconfigure
      -backend-config="address=${TF_STATE_ADDRESS}"
      -backend-config="lock_address=${TF_STATE_ADDRESS}/lock"
      -backend-config="unlock_address=${TF_STATE_ADDRESS}/lock"
      -backend-config="username=gitlab-ci-token"
      -backend-config="password=$CI_JOB_TOKEN"
      -backend-config="lock_method=POST"
      -backend-config="unlock_method=DELETE"
      -backend-config="retry_wait_min=5"
    - terraform apply
      -input=false
      -auto-approve
      -var docker_image="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
      -var ssh_cert="$SSH_PRIVATE_KEY"
      -var docker_image_registry_login="gitlab-ci-token"
      -var docker_image_registry_password="$CI_JOB_TOKEN"

You need to have gitlab variable SSH_PRIVATE_KEY with private key, added in step two.

Example terraform configuration

variable "ssh_cert" {
  type = string
  description = "SSH cert"
}

variable "docker_image" {
  type = string
  description = "Docker image to deploy"
}

variable "docker_image_registry_login" {
  type = string
  description = "Login for Registry of your docker image"
}

variable "docker_image_registry_password" {
  type = string
  description = "Password for Registry of your docker image"
}

terraform {
  required_providers {
    dokku = {
      source = "registry.terraform.io/aliksend/dokku"
    }
  }

  backend "http" {}
}

provider "dokku" {
  ...
  ssh_cert = var.ssh_cert
}

resource "dokku_app" "appname" {
  ...

  deploy = {
    type = "docker_image"
    login = var.docker_image_registry_login
    password = var.docker_image_registry_password
    docker_image = var.docker_image
  }
}

Developing the Provider

If you wish to work on the provider, you'll first need Go installed on your machine (see Requirements below).

To compile the provider, run go install. This will build the provider and put the provider binary in the $GOPATH/bin directory.

To generate or update documentation, run go generate ./....

Requirements

• Terraform >= 1.0
• Go >= 1.19

Building The Provider

1. Clone the repository
2. Enter the repository directory
3. Build the provider using the Go install command:

go install .