From e46a56fe3ec33999cdebbf1ebddbcb58d24dc6a3 Mon Sep 17 00:00:00 2001 From: Luke Murphy Date: Mon, 13 Apr 2020 13:00:14 +0200 Subject: [PATCH] Sum up with shorter docs --- DESIGN.md | 68 ------------------------------------------------------- README.md | 27 +++++++++++----------- 2 files changed, 13 insertions(+), 82 deletions(-) delete mode 100644 DESIGN.md diff --git a/DESIGN.md b/DESIGN.md deleted file mode 100644 index fe1f706..0000000 --- a/DESIGN.md +++ /dev/null @@ -1,68 +0,0 @@ -# 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. diff --git a/README.md b/README.md index 79cdf48..1e83413 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,21 @@ # dokku-ansible-deploy +## Overview + Deploy applications on Dokku using Ansible. -It is a work in progress, please see the following planning documents: +When we package and deploy applications with Dokku, we still have a number of +manual tasks to complete before the application is production ready. Running +Dokku host side commands such as `dokku letsencrypt`, creating and linking +database stores and even going ahead and wiring up monitoring and alerting +infrastructure. -- [DESIGN.md](./DESIGN.md) -- [dokku-packaging-format.md](https://git.autonomic.zone/autonomic-cooperative/organising/wiki/dokku-packaging-format) +This plugin automates what would be otherwise manual steps. Once you `git push` +your application deployment, this plugin consumes configuration specified by in +the `deploy.d` directory to carry out the end-to-end production deployment +steps. + +More documentation coming soon TM. ## Requirements @@ -16,15 +26,4 @@ It is a work in progress, please see the following planning documents: ```bash $ dokku plugin:install https://git.autonomic.zone/autonomic-cooperative/dokku-ansible-deploy.git -$ dokku plugin:install-dependencies ``` - -## Usage - -```bash -$ dokku dokku-deploy:vault-password myapp -``` - -## Contribute - -TODO.