dokku-ansible-deploy/DESIGN.md

design

!!! This is still a work in progress !!!

Overview

The end-user will create an application repository which will contain a number of files which match the autonomic dokku packaging format and will then create a dokku git remote and push to it. On the Dokku server side, this plugin, ansible-dokku-deploy, will intercept the dokku deployment process via the plugin interface and run a number of steps based on the standard dokku plugin triggers.

The idea is that the end-user will only need to specify a few configuration details like the listening port and some application specific details like which database to use and so on and then the plugin will take care to provision and deploy end-to-end the application with port mappings, TLS certificates, DNS entries, databases, automated backups and monitoring.

This plugin will use Ansible to handle the provisioning and deployment process because the Dokku maintainers are actively developing an Ansible library for this purpose and reduces maintenance burden of interacting with Dokku via the command-line which can be a bit tricky to script.

The workings of Ansible should be completely unknown to the end-user unless they need to arrange some custom deployment steps beyond the standard ones we define. That can unfortunately often be the case with complicated applications like Gitea which requires the host system to pass SSH connections through into the container but at least this plugin has shown that it can allow for such flexibility. So, advanced application packagers can leverage Ansible if they need it and for simple applications or pre-packaged applications, the work will already be done.

Pre-requisites

On the Dokku host.

$ dokku plugin:install https://github.com/decentral1se/dokku-ansible-deploy.git
$ dokku plugin:install-dependencies
$ dokku ansible-deploy:vault-password $APP  # add per-app vault password for secrets decrypting

In the application repository (still to be implemented).

$ echo "TODO"

Triggers

post-extract

1. Check if there is a deploy.d folder in the application repository
2. If not, just output a message about skipping and stop execution
3. If so, create an internal deploy folder (e.g. $DOKKU_LIB_ROOT/data/deploy.d/$APP)
4. Copy over all application deploy files to the internal folder (e.g. cp -r "$TMPDIR/deploy.d/." "$DOKKU_LIB_ROOT/data/deploy.d/$APP")
5. Generate a vault password file and set correct permissions for protection

pre-deploy

1. Run internal playbooks to do pre-deploy step tasks (see steps docs) as well as custom application plays (defined in application repository), passing in environment and threading environment into other tasks.

post-deploy

1. Run internal playbooks to do pre-deploy step tasks (see steps docs) as well as custom application plays (defined in application repository), passing in environment and threading environment into other tasks.