Ansible Role: Dokku

This Ansible role helps install Dokku on Debian/Ubuntu variants. Apart from installing Dokku, it also provides various modules that can be used to interface with dokku from your own Ansible playbooks.

Table Of Contents

• Requirements
• Dependencies
• Role Variables
• Libraries
• Example Playbooks
• Contributing
• License

Requirements

Minimum Ansible Version: 2.2

Platform Requirements

Supported Platforms

• Ubuntu: noble
• Ubuntu: jammy
• Ubuntu: focal
• Debian: bookworm
• Debian: bullseye

Dependencies

• geerlingguy.docker ansible role
• nginxinc.nginx ansible role
• Dokku (for library usage)

Role Variables

dokku_daemon_install

• default: True
• type: boolean
• description: Whether to install the dokku-daemon

dokku_daemon_version

• default: 0.0.2
• type: string
• description: The version of dokku-daemon to install

dokku_hostname

• default: dokku.me
• type: string
• description: Hostname, used as vhost domain and for showing app URL after deploy

dokku_key_file

• default: /root/.ssh/id_rsa.pub
• type: string
• description: Path on disk to an SSH key to add to the Dokku user (Will be ignored on dpkg-reconfigure)

dokku_manage_nginx

• default: True
• type: boolean
• description: Whether we should manage the 00-default nginx site

dokku_packages_state

• default: present
• type: string
• description: State of dokku packages. Accepts ‘present’ and ‘latest’

dokku_plugins

• default: {}
• type: list
• description: A list of plugins to install. The host must have network access to the install url, and git access if required. Plugins should be specified in the following format:

- name: postgres
  url: https://github.com/dokku/dokku-postgres.git

- name: redis
  url: https://github.com/dokku/dokku-redis.git

dokku_skip_key_file

• default: false
• type: string
• description: Do not check for the existence of the dokku/key_file. Setting this to “true”, will require you to manually add an SSH key later on.

dokku_users

• default: null
• type: list
• description: A list of users who should have access to Dokku. This will not grant them generic SSH access, but rather only access as the dokku user. Users should be specified in the following format:

- name: Jane Doe
  username: jane
  ssh_key: JANES_PUBLIC_SSH_KEY
- name: Camilla
  username: camilla
  ssh_key: CAMILLAS_PUBLIC_SSH_KEY

dokku_version (deprecated)

• default: ''
• type: string
• description: The version of dokku to install. Scheduled for deletion after 07/2021. Use dokku_packages_state instead.

dokku_vhost_enable

• default: true
• type: string
• description: Use vhost-based deployments (e.g., .dokku.me)

dokku_web_config

• default: false
• type: string
• description: Use web-based config for hostname and keyfile

herokuish_version (deprecated)

• default: ''
• type: string
• description: The version of herokuish to install. Scheduled for deletion after 07/2021. Use dokku_packages_state instead.

plugn_version (deprecated)

• default: ''
• type: string
• description: The version of plugn to install. Scheduled for deletion after 07/2021. Use dokku_packages_state instead.

sshcommand_version (deprecated)

• default: ''
• type: string
• description: The version of sshcommand to install. Scheduled for deletion after 07/2021. Use dokku_packages_state instead.

Libraries

dokku_acl_app

Manage access control list for a given dokku application

Requirements

• the dokku-acl plugin

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
state	Choices: present (default) absent	Whether the ACLs should be present or absent
users required		The list of users who can manage the app

Example

- name: let leopold manage hello-world
  dokku_acl_app:
    app: hello-world
    users:
      - leopold
- name: remove leopold from hello-world
  dokku_acl_app:
    app: hello-world
    users:
      - leopold
    state: absent

dokku_acl_service

Manage access control list for a given dokku service

Requirements

• the dokku-acl plugin

Parameters

Parameter	Choices/Defaults	Comments
service required		The name of the service
state	Choices: present (default) absent	Whether the ACLs should be present or absent
type required		The type of the service
users required		The list of users who can manage the service

Example

- name: let leopold manage mypostgres postgres service
  dokku_acl_service:
    service: mypostgres
    type: postgres
    users:
      - leopold
- name: remove leopold from mypostgres postgres service
  dokku_acl_service:
    service: hello-world
    type: postgres
    users:
      - leopold
    state: absent

dokku_app

Create or destroy dokku apps

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
state	Choices: present (default) absent	The state of the app

Example

- name: Create a dokku app
  dokku_app:
    app: hello-world

- name: Delete that repo
  dokku_app:
    app: hello-world
    state: absent

dokku_builder

Manage the builder configuration for a given dokku application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app. This is required only if global is set to False.
global	Default: False	If the property being set is global
property required		The property to be changed (e.g., build-dir, selected)
value		The value of the builder property (leave empty to unset)

Example

- name: Overriding the auto-selected builder
  dokku_builder:
    app: node-js-app
    property: selected
    value: dockerfile
- name: Setting the builder to the default value
  dokku_builder:
    app: node-js-app
    property: selected
- name: Changing the build build directory
  dokku_builder:
    app: monorepo
    property: build-dir
    value: backend
- name: Overriding the auto-selected builder globally
  dokku_builder:
    global: true
    property: selected
    value: herokuish

dokku_certs

Manages ssl configuration for an app.

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
cert required		Path to the ssl certificate
key required		Path to the ssl certificate key
state	Choices: present (default) absent	The state of the ssl configuration

Example

- name: Adds an ssl certificate and key to an app
  dokku_certs:
    app: hello-world
    key: /etc/nginx/ssl/hello-world.key
    cert: /etc/nginx/ssl/hello-world.crt

- name: Removes an ssl certificate and key from an app
  dokku_certs:
    app: hello-world
    state: absent

dokku_checks

Manage the Zero Downtime checks for a dokku app

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
state	Choices: present (default) absent	The state of the checks functionality

Example

- name: Disable the zero downtime deployment
  dokku_checks:
    app: hello-world
    state: absent

- name: Re-enable the zero downtime deployment (enabled by default)
  dokku_checks:
    app: hello-world
    state: present

dokku_clone

Clone a git repository and deploy app.

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
build	Default: True	Whether to build the app after cloning.
repository required		Git repository url
version		Git tree (tag or branch name). If not provided, default branch is used.

Example

- name: clone a git repository and build app
  dokku_clone:
      app: example-app
      repository: https://github.com/heroku/node-js-getting-started
      version: b10a4d7a20a6bbe49655769c526a2b424e0e5d0b
- name: clone specific tag from git repository and build app
  dokku_clone:
      app: example-app
      repository: https://github.com/heroku/node-js-getting-started
      version: b10a4d7a20a6bbe49655769c526a2b424e0e5d0b
- name: sync git repository without building app
  dokku_clone:
      app: example-app
      repository: https://github.com/heroku/node-js-getting-started
      build: false

dokku_config

Manage environment variables for a given dokku application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
config required	Default: {}	A map of environment variables where key => value
restart	Default: True	Whether to restart the application or not. If the task is idempotent then setting restart to true will not perform a restart.

Example

- name: set KEY=VALUE
  dokku_config:
    app: hello-world
    config:
      KEY: VALUE_1
      KEY_2: VALUE_2

- name: set KEY=VALUE without restart
  dokku_config:
    app: hello-world
    restart: false
    config:
      KEY: VALUE_1
      KEY_2: VALUE_2

dokku_docker_options

Manage docker-options for a given dokku application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
option required		A single docker option
phase	Choices: build deploy run	The phase in which to set the options
state	Choices: present (default) absent	The state of the docker options

Example

- name: docker-options:add hello-world deploy
  dokku_docker_options:
    app: hello-world
    phase: deploy
    option: "-v /var/run/docker.sock:/var/run/docker.sock"

- name: docker-options:remove hello-world deploy
  dokku_docker_options:
    app: hello-world
    phase: deploy
    option: "-v /var/run/docker.sock:/var/run/docker.sock"
    state: absent

dokku_domains

Manages domains for a given application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app. This is required only if global is set to False.
domains required		A list of domains
global	Default: False	Whether to change the global domains or app-specific domains.
state	Choices: enable disable clear present (default) absent set	The state of the application’s domains

Example

# Adds domain, inclusive
- name: domains:add hello-world dokku.me
  dokku_domains:
    app: hello-world
    domains:
      - dokku.me

# Removes listed domains, but leaves others unchanged
- name: domains:remove hello-world dokku.me
  dokku_domains:
    app: hello-world
    domains:
      - dokku.me
    state: absent

# Clears all domains
- name: domains:clear hello-world
  dokku_domains:
    app: hello-world
    state: clear

# Enables the VHOST domain
- name: domains:enable hello-world
  dokku_domains:
    app: hello-world
    state: enable

# Disables the VHOST domain
- name: domains:disable hello-world
  dokku_domains:
    app: hello-world
    state: disable

# Sets the domain for the app, clearing all others
- name: domains:set hello-world dokku.me
  dokku_domains:
    app: hello-world
    domains:
      - dokku.me
    state: set

dokku_git_sync

Manages syncing git code from a remote repository for an app

Requirements

• the dokku-git-sync plugin (commercial)

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
remote		The git remote url to use
state	Choices: present (default) absent	The state of the git-sync integration

Example

- name: git-sync:enable hello-world
  dokku_git_sync:
    app: hello-world
    remote: git@github.com:hello-world/hello-world.git

- name: git-sync:disable hello-world
  dokku_git_sync:
    app: hello-world
    state: absent

dokku_global_cert

Manages global ssl configuration.

Requirements

• the dokku-global-cert plugin

Parameters

Parameter	Choices/Defaults	Comments
cert required		Path to the ssl certificate
key required		Path to the ssl certificate key
state	Choices: present (default) absent	The state of the ssl configuration

Example

- name: Adds an ssl certificate and key
  dokku_global_cert:
    key: /etc/nginx/ssl/global-hello-world.key
    cert: /etc/nginx/ssl/global-hello-world.crt

- name: Removes an ssl certificate and key
  dokku_global_cert:
    state: absent

dokku_http_auth

Manage HTTP Basic Authentication for a dokku app

Requirements

• the dokku-http-auth plugin

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
password		The HTTP Auth Password (required for ‘present’ state)
state	Choices: present (default) absent	The state of the http-auth plugin
username		The HTTP Auth Username (required for ‘present’ state)

Example

- name: Enable the http-auth plugin
  dokku_http_auth:
    app: hello-world
    state: present
    username: samsepi0l
    password: hunter2

- name: Disable the http-auth plugin
  dokku_http_auth:
    app: hello-world
    state: absent

dokku_image

Pull Docker image and deploy app

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
build_dir		Specify custom build directory for a custom build context
image required		Docker image
user_email		Git user.email for customizing the author’s email
user_name		Git user.name for customizing the author’s name

Example

- name: Pull and deploy meilisearch
  dokku_image:
      app: meilisearch
      image: getmeili/meilisearch:v0.24.0rc1
- name: Pull and deploy image with custom author
  dokku_image:
      app: hello-world
      user_name: Elliot Alderson
      user_email: elliotalderson@protonmail.ch
      image: hello-world:latest
- name: Pull and deploy image with custom build dir
  dokku_image:
      app: hello-world
      build_dir: /path/to/build
      image: hello-world:latest

dokku_letsencrypt

Enable or disable the letsencrypt plugin for a dokku app

Requirements

• the dokku-letsencrypt plugin

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
state	Choices: present (default) absent	The state of the letsencrypt plugin

Example

- name: Enable the letsencrypt plugin
  dokku_letsencrypt:
    app: hello-world

- name: Disable the letsencrypt plugin
  dokku_letsencrypt:
    app: hello-world
    state: absent

dokku_network

Create or destroy container networks for dokku apps

Parameters

Parameter	Choices/Defaults	Comments
name required		The name of the network
state	Choices: present (default) absent	The state of the network

Example

- name: Create a network
  dokku_network:
    name: example-network

- name: Delete that network
  dokku_network:
    name: example-network
    state: absent

dokku_network_property

Set or clear a network property for a given dokku application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app. This is required only if global is set to False.
global	Default: False	Whether to change the global network property
property required		The network property to be be modified. This can be any property supported by dokku (e.g., initial-network, attach-post-create, attach-post-deploy, bind-all-interfaces, static-web-listener, tld).
value		The value of the network property (leave empty to unset)

Example

- name: Associates a network after a container is created but before it is started
  dokku_network_property:
    app: hello-world
    property: attach-post-create
    value: example-network

- name: Associates the network at container creation
  dokku_network_property:
    app: hello-world
    property: initial-network
    value: example-network

- name: Setting a global network property
  dokku_network_property:
    global: true
    property: attach-post-create
    value: example-network

- name: Clearing a network property
  dokku_network_property:
    app: hello-world
    property: attach-post-create

dokku_ports

Manage ports for a given dokku application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
mappings required		A list of port mappings
state	Choices: clear present (default) absent	The state of the port mappings

Example

- name: ports:set hello-world http:80:80
  dokku_ports:
    app: hello-world
    mappings:
        - http:80:8080

- name: ports:remove hello-world http:80:80
  dokku_ports:
    app: hello-world
    mappings:
        - http:80:8080
    state: absent

- name: ports:clear hello-world
  dokku_ports:
    app: hello-world
    state: clear

dokku_proxy

Enable or disable the proxy for a dokku app

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
state	Choices: present (default) absent	The state of the proxy

Example

- name: Enable the default proxy
  dokku_proxy:
    app: hello-world

- name: Disable the default proxy
  dokku_proxy:
    app: hello-world
    state: absent

dokku_ps_scale

Manage process scaling for a given dokku application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
scale required	Default: {}	A map of scale values where proctype => qty
skip_deploy	Default: False	Whether to skip the corresponding deploy or not. If the task is idempotent then leaving skip_deploy as false will not trigger a deploy.

Example

- name: scale web and worker processes
  dokku_ps_scale:
    app: hello-world
    scale:
      web: 4
      worker: 4

- name: scale web and worker processes without deploy
  dokku_ps_scale:
    app: hello-world
    skip_deploy: true
    scale:
      web: 4
      worker: 4

dokku_registry

Manage the registry configuration for a given dokku application

Requirements

• the dokku-registry plugin

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
image		Alternative to app name for image repository name
password		The registry password (required for ‘present’ state)
server		The registry server hostname (required for ‘present’ state)
state	Choices: present (default) absent	The state of the registry integration
username		The registry username (required for ‘present’ state)

Example

- name: registry:enable hello-world
  dokku_registry:
    app: hello-world
    password: password
    server: localhost:8080
    username: user

- name: registry:enable hello-world with args
  dokku_registry:
    app: hello-world
    image: other-image
    password: password
    server: localhost:8080
    username: user

- name: registry:disable hello-world
  dokku_registry:
    app: hello-world
    state: absent

dokku_resource_limit

Manage resource limits for a given dokku application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
clear_before	Choices: True False (default)	Clear all resource limits before applying
process_type		The process type selector
resources		The Resource type and quantity (required when state=present)
state	Choices: present (default) absent	The state of the resource limits

Example

- name: Limit CPU and memory of a dokku app
  dokku_resource_limit:
    app: hello-world
    resources:
      cpu: 100
      memory: 100

- name: name: Limit resources per process type of a dokku app
  dokku_resource_limit:
    app: hello-world
    process_type: web
    resources:
      cpu: 100
      memory: 100

- name: Clear limits before applying new limits
  dokku_resource_limit:
    app: hello-world
    state: present
    clear_before: True
    resources:
      cpu: 100
      memory: 100

- name: Remove all resource limits
  dokku_resource_limit:
    app: hello-world
    state: absent

dokku_resource_reserve

Manage resource reservations for a given dokku application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
clear_before	Choices: True False (default)	Clear all reserves before apply
process_type		The process type selector
resources		The Resource type and quantity (required when state=present)
state	Choices: present (default) absent	The state of the resource reservations

Example

- name: Reserve CPU and memory for a dokku app
  dokku_resource_reserve:
    app: hello-world
    resources:
      cpu: 100
      memory: 100

- name: Create a reservation per process type of a dokku app
  dokku_resource_reserve:
    app: hello-world
    process_type: web
    resources:
      cpu: 100
      memory: 100

- name: Clear all reservations before applying
  dokku_resource_reserve:
    app: hello-world
    state: present
    clear_before: True
    resources:
      cpu: 100
      memory: 100

- name: Remove all resource reservations
  dokku_resource_reserve:
    app: hello-world
    state: absent

dokku_service_create

Creates a given service

Parameters

Parameter	Choices/Defaults	Comments
name required		The name of the service
service required		The type of service to create

Example

- name: redis:create default
  dokku_service_create:
    name: default
    service: redis

- name: postgres:create default
  dokku_service_create:
    name: default
    service: postgres

- name: postgres:create default with custom image
  environment:
    POSTGRES_IMAGE: postgis/postgis
    POSTGRES_IMAGE_VERSION: 13-master
  dokku_service_create:
    name: default
    service: postgres

dokku_service_link

Links and unlinks a given service to an application

Parameters

Parameter	Choices/Defaults	Comments
app required		The name of the app
name required		The name of the service
service required		The type of service to link
state	Choices: present (default) absent	The state of the service link

Example

- name: redis:link default hello-world
  dokku_service_link:
    app: hello-world
    name: default
    service: redis

- name: postgres:link default hello-world
  dokku_service_link:
    app: hello-world
    name: default
    service: postgres

- name: redis:unlink default hello-world
  dokku_service_link:
    app: hello-world
    name: default
    service: redis
    state: absent

dokku_storage

Manage storage for dokku applications

Parameters

Parameter	Choices/Defaults	Comments
app		The name of the app
create_host_dir	Default: False	Whether to create the host directory or not
group	Default: 32767	A group or gid that should own the created folder
mounts	Default: []	A list of mounts to create, colon (:) delimited, in the format: host_dir:container_dir
state	Choices: present (default) absent	The state of the service link
user	Default: 32767	A user or uid that should own the created folder

Example

- name: mount a path
  dokku_storage:
    app: hello-world
    mounts:
      - /var/lib/dokku/data/storage/hello-world:/data

- name: mount a path and create the host_dir directory
  dokku_storage:
    app: hello-world
    mounts:
      - /var/lib/dokku/data/storage/hello-world:/data
    create_host_dir: true

- name: unmount a path
  dokku_storage:
    app: hello-world
    mounts:
      - /var/lib/dokku/data/storage/hello-world:/data
    state: absent

- name: unmount a path and destroy the host_dir directory (and contents)
  dokku_storage:
    app: hello-world
    mounts:
      - /var/lib/dokku/data/storage/hello-world:/data
    destroy_host_dir: true
    state: absent

Example Playbooks

Installing Dokku

---
- hosts: all
  roles:
    - dokku_bot.ansible_dokku

Installing Plugins

---
- hosts: all
  roles:
    - dokku_bot.ansible_dokku
  vars:
    dokku_plugins:
      - name: clone
        url: https://github.com/crisward/dokku-clone.git
      - name: postgres
        url: https://github.com/dokku/dokku-postgres.git

Deploying a simple word inflector

---
- hosts: all
  roles:
    - dokku_bot.ansible_dokku
  tasks:
    - name: dokku apps:create inflector
      dokku_app:
        app: inflector

    - name: dokku clone inflector
      dokku_clone:
        app: inflector
        repository: https://github.com/cakephp/inflector.cakephp.org

Setting up a Small VPS with a Dokku App

---
- hosts: all
  roles:
    - dokku_bot.ansible_dokku
    - geerlingguy.swap
  vars:
    # If you are running dokku on a small VPS, you'll most likely
    # need some swap to ensure you don't run out of RAM during deploys
    swap_file_size_mb: '2048'
    dokku_version: 0.19.13
    dokku_users:
      - name: yourname
        username: yourname
        ssh_key: "{{lookup('file', '~/.ssh/id_rsa.pub')}}"
    dokku_plugins:
      - name: clone
        url: https://github.com/crisward/dokku-clone.git
      - name: letsencrypt
        url: https://github.com/dokku/dokku-letsencrypt.git
  tasks:
    - name: create app
      dokku_app:
        # change this name in your template!
        app: &appname appname
    - name: environment configuration
      dokku_config:
        app: *appname
        config:
          # specify port so `domains` can setup the port mapping properly
          PORT: "5000"
    - name: git clone
      # note you'll need to add a deployment key to the GH repo if it's private!
      dokku_clone:
        app: *appname
        repository: git@github.com:heroku/python-getting-started.git
    - name: add domain
      dokku_domains:
        app: *appname
        domains:
          - example.com
    - name: add letsencrypt
      dokku_letsencrypt:
        app: *appname

Contributing

See CONTRIBUTING.md.

License

MIT License

See LICENSE.md for further details.