chef-dokku

Manages a dokku installation, allowing
configuration of application's environment variables,
installation of plugins and
management of ssh keys.

Usage

Include the bootstrap recipe in your run list to have dokku installed/updated
during chef runs.

Attributes

These attributes are under the node['dokku'] namespace.

Configuration

While this cookbook will be able to provide you with a working dokku installation,
there is some configuration you will likely want to do first:

SSH Keys

This is a required step to getting dokku working. You will want to set
node['dokku']['ssh_keys'] to a hash of the following structure:

default['dokku']['ssh_keys'] = {
  'awesome_user' => 'awesome_users_pubkey',
  'superb_user' => 'superb_users_pubkey'
}

The ssh_keys recipe will handle
setting up the keys for dokku

Apps

Pre-configured applications. These attributes are used to configure environment
variables or remove an app:

default['dokku']['apps'] = {
  'cool_app' => {
    'env' => {
      'ENV_VAR' => 'ENV_VAR_VALUE',
      'ENV_VAR2' => 'ENV_VAR2_VALUE'
    }
  }
}

Plugins

You will likely want to install plugins to expand the functionality of your
dokku installation. See the dokku wiki page
for a list of available plugins.

Plugins are defined on the node['dokku']['plugins'] attribute:

default['dokku']['plugins'] = {
  'plugin_name' => 'plugin_repository_url',
  # For example:
  'postgresql' => 'https://github.com/Kloadut/dokku-pg-plugin'
}

Applications Attributes

These attributes are under the node['dokku']['apps']['YOUR_APP_NAME'] namespace.

Sync attributes

These attributes are under the node['dokku']['sync'] namespace. They control
whether remote code bases will be updated on chef runs

Build Stack attributes

These attributes are under the node['dokku']['buildstack'] namespace. They
correspond to the buildstep that is
used by dokku.

PluginHook Attributes

These attributes are under the node['dokku']['pluginhook'] namespace.

Recipes

• recipe[dokku] - Noop. Will be used to include LWRPs in the future
• recipe[dokku::bootstrap] - A chef version of bootstrap.sh. Include this recipe to have dokku installed/updated by chef
• recipe[dokku::install] - Clones/checks out the dokku git repository and copies the required files via make copyfiles
• recipe[dokku::buildstack] - Builds/imports the dokku buildstep docker image. See node['dokku']['buildstack']['use_prebuilt'] to set which buildstep is imported

Testing and Development

Vagrant

Here's how you can quickly get testing or developing against the cookbook thanks
to Vagrant.

vagrant plugin install vagrant-omnibus
git clone git://github.com/fgrehm/chef-dokku.git
cd chef-dokku
bundle install
bundle exec berks install -p vendor/cookbooks
vagrant up

You can then SSH into the running VM using the vagrant ssh command.

The VM can easily be stopped and deleted with the vagrant destroy command.
Please see the official Vagrant documentation
for a more in depth explanation of available commands.

Roadmap

• Convert things like ssh keys, app env, etc to LWPRs w/ Chefspec v3 matchers
• Reduce rewritten/overridden areas of the bootstrap process to better keep up with dokku's rapid development
• Plugin removal
• Use dokku app removal process
• Support dokku addons