Run ansible playbooks during deployment
This repository has been archived on 2020-05-08. You can view files and clone it, but cannot push or open issues or pull requests.
Go to file
Luke Murphy bdec39b591
Drop back verbosity
2020-04-01 11:04:03 +02:00
subcommands Shuffle functions into place 2020-03-22 00:33:12 +01:00
LICENSE Another push to get this out the door 2020-03-19 01:43:41 +01:00 Add more examples 2020-03-22 12:46:32 +01:00
commands Fix command name 2020-03-22 00:50:52 +01:00
dependencies Add common functions 2020-03-19 23:45:06 +01:00
functions Drop back verbosity 2020-04-01 11:04:03 +02:00
plugin.toml Bootstrap this plugin 2020-03-19 01:13:54 +01:00
post-delete Add post-delete hook 2020-03-22 12:11:21 +01:00
post-deploy Use new function name 2020-03-22 02:19:24 +01:00
post-extract Don't wildcard in quotes 2020-03-21 01:49:08 +01:00
pre-deploy Use new function name 2020-03-22 02:19:24 +01:00


Run ansible playbooks during deployment.

This plugin can be useful when you need to provision your server before or after a deployment of your application (or on any hook, just raise an issue and let's add it) and you prefer to use Ansible instead of Bash for certain tasks. Bash can still be the right tool for other things but sometimes, it can be become tricky to manage the idempotent case in Bash.

For example, you can make use of the official ansible-dokku roles.


  • dokku 0.19.13+
  • Debian based system (uses apt package manager for installing dependencies)


$ dokku plugin:install
$ dokku plugin:install-dependencies


All files must be placed within the ansible folder of your git repository. Everything is copied into $DOKKU_LIB_ROOT/data/ansible/$APP on the post-extract hook. Dokku will make sure that your Ansible plays are run on various hooks against the Dokku server localhost.

  • requirements.yml: what role dependencies to download before running your plays.
  • pre-deploy.yml: play run before a deployment
  • post-deploy.yml: play run after a deployment
  • post-delete.yml: play run after an application delete
  • vars/...: variable files (you'll need to include manually with the include_vars module)


Ansible uses the vault password file which can be used to decrypt secrets.

To get started with enabling this, you should generate a vault password for your self and run the following on your Dokku host.

$ dokku ansible-playbook:vault-pass

Then you can start to encrypt your passwords on your local machine with the following.

$ ansible-vault \
  encrypt_string \
  --vault-password-file ansible/ \
  --name mysecretname \

Where ansible/ might look like this.


set -eu -o pipefail

echo "my-cool-vault-password"

Then for example, if you want to pass a sudo password, you might include a vars/ansible_become_password.yml.

ansible_become_password: !vault ...


Since the dokku user account runs the plays on the host, you will need to deal with sudo permissions when you want to use become: true to run a privilege escalation to the root account. You can give your dokku user account passwordless sudo access but that would give a lot of power to people who can get access to that user account. A solution to this can be to add your dokku to the sudoers group, give the account a password (passwd dokku && usermod -aG sudo dokku) and pass ansible_become_password in as a variable.

Injected variables

Same as the plugin available variables but in your Ansible plays.

  • dokku_lib_root



- src: dokku_bot.ansible_dokku
  version: v2020.3.15


ansible_become_pass: !vault |


- hosts: all
    - name: Load variables
        dir: "{{ dokku_lib_root }}/data/ansible/gitea/vars/"
          - yml

    - name: Configure the foobar environment
        app: foobar
        restart: false
          FOO: "BAR"

    - name: Setup host group
        name: barfoo
        system: true
        state: present
      become: true