Dokku Graduate
Dokku Graduate is a simple plug-in for Dokku that helps manage the deployment of multiple Dokku apps to multiple environments (development, staging, UAT, production etc).
What problem does this plugin solve?
Larger projects are frequently made up of multiple apps. Whilst Dokku does a fantastic job of managing individual apps and making their deployment a breeze. Dokku does not directly handle the situation of having multiple apps that interact with each other, or depend on each other.
An Example
Say we have two Dokku apps running in both development and in production. One app is a Rails website, called portal, and the other is set of Sinatra web-services called webservices. Both of these apps share the same data mode, and the same data store (e.g. a PostgreSQL database). portal is an admin interface and webservices is for consumers.
We want to deploy updated projects with a new data model to production. Typically you'd write a Rails migration which you could then kick off as a Dokku hook, or perhaps manually once portal has deployed to production. However, what happens to webservices, which is also using the same data store? A new webservices that understands the updated data model also needs to be deployed.
We can't deploy webservices after portal and the migration have run, because after the migration has run the old webservices will still be running and trying to use the old data model with the new data store structure.
We can't deploy the new webservices before portal, because the migration is yet to run and webservices will try use the new data model on the old data store. This would be particularly problematic if portal failed to deploy!
Dokku Graduate helps solve this problem.
How does it work?
Dokku Graduate allows you to graduate an entire set of apps in one environment to another environment. However, we do not simply deploy all the apps and let them go live one at a time. Apps will not go live (e.g. have their ports exposed) until they themselves, and all their peers, have passed Dokku's check-install phase.
Dokku Graduate also provides its own set of hooks, including its own POST [deployment] hook, that is called after every app has deployed and passed Dokku's check-install phase. Dokku Graduate's POST hook gives you an opportunity to kick off a process that will affect multiple apps running in the one environment (e.g. a database migration), or run any sort of environment wide tests. If a POST hook fails, then the whole graduation is aborted, and none of the apps will go live.
Back to the example
Using Dokku Graduate, we would perform our database migration as a POST hook. Then we would graduate from development to production; deploying both apps to production and performing Dokku check-install hooks for both portal and webservices, and our database migration (the Dokku Graduate POST hook) before anything becomes publicly accessible. If either app fails to deploy, or the migration were to fail then the entire graduation would be aborted ensuring production is not left in broken state. Great!
Note: I feel I should mention that, in this example, there is still a small window of time where you would have to take some care to ensure that the old (publicly accessible) app/Docker instances for portal and webservices don't try access the data store during/after the migration.
To be clear, Dokku Graduate isn't just useful for database migrations. It's also very useful if you have apps that depend on each other. For example, if portal were to consume private web services provided by webservices and you want to change the API. Or, perhaps if portal and webservices mutually consume each others' functionality!
I'm sold. How do I get started?
Please refer to the README on Github.