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](https://git.autonomic.zone/autonomic-cooperative/organising/wiki/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](https://github.com/dokku/dokku/blob/master/docs/development/plugin-triggers.md).

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](https://github.com/dokku/ansible-dokku/)
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.

```bash
$ 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).

```bash
$ echo "TODO"
```

## Triggers

### post-extract

1. Check if there is a `deploy.d` folder in the application repository
1. If not, just output a message about skipping and stop execution
1. If so, create an internal deploy folder (e.g. `$DOKKU_LIB_ROOT/data/deploy.d/$APP`)
1. Copy over all application deploy files to the internal folder (e.g. `cp -r "$TMPDIR/deploy.d/." "$DOKKU_LIB_ROOT/data/deploy.d/$APP"`)
1. 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](https://git.autonomic.zone/autonomic-cooperative/organising/wiki/dokku-deploy-steps#user-content-pre-deploy) 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](https://git.autonomic.zone/autonomic-cooperative/organising/wiki/dokku-deploy-steps#user-content-post-deploy) docs)
   as well as custom application plays (defined in application repository), passing in environment and threading environment into other tasks.