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.
Minimum Ansible Version: 2.2
Supported Platforms
- Ubuntu: noble
- Ubuntu: jammy
- Ubuntu: focal
- Debian: bookworm
- Debian: bullseye
- geerlingguy.docker ansible role
- nginxinc.nginx ansible role
- Dokku (for library usage)
- default: True
- type: boolean
- description: Whether to install the dokku-daemon
- default: 0.0.2
- type: string
- description: The version of dokku-daemon to install
- default: dokku.me
- type: string
- description: Hostname, used as vhost domain and for showing app URL after deploy
- 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)
- default: True
- type: boolean
- description: Whether we should manage the 00-default nginx site
- default: present
- type: string
- description: State of dokku packages. Accepts 'present' and 'latest'
- 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- 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.
- 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 dokkuuser. 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- default: ''
- type: string
- description: The version of dokku to install.
Scheduled for deletion after 07/2021. Use dokku_packages_stateinstead.
- default: true
- type: string
- description: Use vhost-based deployments (e.g., .dokku.me)
- default: false
- type: string
- description: Use web-based config for hostname and keyfile
- default: ''
- type: string
- description: The version of herokuish to install.
Scheduled for deletion after 07/2021. Use dokku_packages_stateinstead.
- default: ''
- type: string
- description: The version of plugn to install.
Scheduled for deletion after 07/2021. Use dokku_packages_stateinstead.
- default: ''
- type: string
- description: The version of sshcommand to install.
Scheduled for deletion after 07/2021. Use dokku_packages_stateinstead.
Manage access control list for a given dokku application
- the dokku-aclplugin
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| state | Choices: 
 | Whether the ACLs should be present or absent | 
| users required | The list of users who can manage the app | 
- 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: absentManage access control list for a given dokku service
- the dokku-aclplugin
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| service required | The name of the service | |
| state | Choices: 
 | 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 | 
- 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: absentCreate or destroy dokku apps
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| state | Choices: 
 | The state of the app | 
- name: Create a dokku app
  dokku_app:
    app: hello-world
- name: Delete that repo
  dokku_app:
    app: hello-world
    state: absentManage the builder configuration for a given dokku application
| 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) | 
- 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: herokuishManages ssl configuration for an app.
| 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: 
 | The state of the ssl configuration | 
- 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: absentManage the Zero Downtime checks for a dokku app
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| state | Choices: 
 | The state of the checks functionality | 
- 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: presentClone a git repository and deploy app.
| 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. | 
- 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: falseManage environment variables for a given dokku application
| 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. | 
- 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_2Manage docker-options for a given dokku application
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| option required | A single docker option | |
| phase | Choices: 
 | The phase in which to set the options | 
| state | Choices: 
 | The state of the docker options | 
- 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: absentManages domains for a given application
| 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: 
 | The state of the application's domains | 
# 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: setManages syncing git code from a remote repository for an app
- the dokku-git-syncplugin (commercial)
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| remote | The git remote url to use | |
| state | Choices: 
 | The state of the git-sync integration | 
- name: git-sync:enable hello-world
  dokku_git_sync:
    app: hello-world
    remote: [email protected]:hello-world/hello-world.git
- name: git-sync:disable hello-world
  dokku_git_sync:
    app: hello-world
    state: absentManages global ssl configuration.
- the dokku-global-certplugin
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| cert required | Path to the ssl certificate | |
| key required | Path to the ssl certificate key | |
| state | Choices: 
 | The state of the ssl configuration | 
- 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: absentManage HTTP Basic Authentication for a dokku app
- the dokku-http-authplugin
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| password | The HTTP Auth Password (required for 'present' state) | |
| state | Choices: 
 | The state of the http-auth plugin | 
| username | The HTTP Auth Username (required for 'present' state) | 
- 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: absentPull Docker image and deploy app
| 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 | 
- 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: [email protected]
      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:latestEnable or disable the letsencrypt plugin for a dokku app
- the dokku-letsencryptplugin
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| state | Choices: 
 | The state of the letsencrypt plugin | 
- name: Enable the letsencrypt plugin
  dokku_letsencrypt:
    app: hello-world
- name: Disable the letsencrypt plugin
  dokku_letsencrypt:
    app: hello-world
    state: absentCreate or destroy container networks for dokku apps
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| name required | The name of the network | |
| state | Choices: 
 | The state of the network | 
- name: Create a network
  dokku_network:
    name: example-network
- name: Delete that network
  dokku_network:
    name: example-network
    state: absentSet or clear a network property for a given dokku application
| 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) | 
- 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-createManage ports for a given dokku application
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| mappings required | A list of port mappings | |
| state | Choices: 
 | The state of the port mappings | 
- 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: clearEnable or disable the proxy for a dokku app
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| state | Choices: 
 | The state of the proxy | 
- name: Enable the default proxy
  dokku_proxy:
    app: hello-world
- name: Disable the default proxy
  dokku_proxy:
    app: hello-world
    state: absentManage process scaling for a given dokku application
| 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. | 
- 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: 4Manage the registry configuration for a given dokku application
- the dokku-registryplugin
| 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: 
 | The state of the registry integration | 
| username | The registry username (required for 'present' state) | 
- 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: absentManage resource limits for a given dokku application
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| clear_before | Choices: 
 | Clear all resource limits before applying | 
| process_type | The process type selector | |
| resources | The Resource type and quantity (required when state=present) | |
| state | Choices: 
 | The state of the resource limits | 
- 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: absentManage resource reservations for a given dokku application
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| app required | The name of the app | |
| clear_before | Choices: 
 | Clear all reserves before apply | 
| process_type | The process type selector | |
| resources | The Resource type and quantity (required when state=present) | |
| state | Choices: 
 | The state of the resource reservations | 
- 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: absentCreates a given service
| Parameter | Choices/Defaults | Comments | 
|---|---|---|
| name required | The name of the service | |
| service required | The type of service to create | 
- 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: postgresLinks and unlinks a given service to an application
| 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: 
 | The state of the service link | 
- 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: absentManage storage for dokku applications
| 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: 
 | The state of the service link | 
| user | Default: 32767 | A user or uid that should own the created folder | 
- 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---
- hosts: all
  roles:
    - dokku_bot.ansible_dokku---
- 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---
- 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---
- 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: [email protected]:heroku/python-getting-started.git
    - name: add domain
      dokku_domains:
        app: *appname
        domains:
          - example.com
    - name: add letsencrypt
      dokku_letsencrypt:
        app: *appnameSee CONTRIBUTING.md.
MIT License
See LICENSE.md for further details.