Capistrano::Cul

Capistrano v3 tasks shared across CUL projects.

This gem provides common cap tasks that are used in almost every cul project. It also includes a set of cap tasks and hooks that are specific for Wordpress deployments. Do not include the Wordpress library if you are not deploying a Wordpress site.

Installation

Install gem

Add this line to your application's Gemfile:

gem 'capistrano-cul', require: false

Note: If installing in a rails application, gem should only be installed in :development and :test groups.

And then execute:

$ bundle

Or install it yourself as:

$ gem install capistrano-cul

Add Capistrano::Cul tasks to Capfile

In your application's Capfile include:

require 'capistrano/cul'

For Wordpress deployments, in your application's Capfile include:

require 'capistrano/cul'
require 'capistrano/cul/wp'

Usage

Shared cap tasks (capistrano/cul)

1. cap {env} cul:auto_tag

   Tags the current commit as the version number provided in VERSION.

2. cap {env} cul:downtime

   Pulls down the downtime branch of the repository to a /downtime directory and symlinks current to downtime. To undo this action, redeploy your application.

Wordpress deployment (capistrano/cul/wp)

Tasks

1. cap {env} cul:wp:setup

   Sets up a WordPress docroot and runs deployment; does not install WordPress and does not create any users.

2. cap {env} cul:wp:install

   Runs a WordPress installation for a newly set up instance and creates a new admin user.

3. cap {env} cul:wp:create_symlinks

   Creates symlinks for custom plugins and themes as part of a WordPress deployment. Generally run as an after :deploy hook.

4. cap {env} cul:wp:searchreplace

   Runs a search and replace operation on the tables in a WordPress installation.

5. cap {env} cul:wp:migrate:copy_from

   Copies the WordPress installation from one environment to another (e.g. prod to dev)

6. cap {env} cul:wp:update:core

   Updates WordPress core to the latest version.

7. cap {env} cul:wp:update:plugins

   Updates non-repo-managed plugins to the latest version.

8. cap {env} cul:wp:update:themes

   Updates non-repo-managed themes to the latest version.

9. cap {env} cul:wp:update:all

   Updates WordPress core, plugins, and themes (in that order) by calling update:core, update:plugins and update:themes tasks.

Configurable variables

The Wordpress tasks listed above require the following variables .

set :wp_docroot # (string) Path to webserver document root for site
set :wp_data_path # (string) Path to data directory (outside of wp_docroot) that contains wp-content
set :url # (string) Public website URL
set :title # (string) Website title
set :multisite # (boolean) Whether or not this is a multisite wordpress installation
# set :multisite_type # (string, only required if :multisite is set) Specifies the type of multisite setup.  Valid values are 'subdirectories' or 'subdomains.
set :wp_custom_plugins # (hash) Map of custom plugin file/directory names to repo-relative paths
set :wp_custom_mu_plugins # (hash) Map of custom MUST-USE plugin file/directory names to repo-relative paths
set :wp_custom_themes # (hash) Map of custom theme file/directory names to repo-relative paths

Here's a sample configuration:

set :wp_docroot, "#{fetch(:deploy_to)}/wp-docroot"
set :multisite, false
set :title, 'Amazing WordPress Site'

set :wp_custom_plugins, {
  'custom-plugin-file.php' => 'plugins/custom-plugin-file.php',
  'custom-plugin-directory' => 'plugins/custom-plugin-directory'
}

# NOTE: It is important that the keys in the hash below match the plugin name
# keys exactly. The zip file url can be any valid, publicly-accessible url.
set :additional_plugins_from_remote_zip, {
   'cf-byline' => 'https://github.com/cul/cf-byline/archive/v1.0.0.zip'
}

set :wp_custom_themes, {
  'mytheme' => 'themes/mytheme'
}
set :wp_content_rsync_exclude_filters, [
  "uploads/2018/01/ignore_this_file.jpg",
  "uploads/2018/02/also_ignore_this_file.jpg",
]

# For this example site, we're symlinking the wp-content/wflogs directory to a corresponding
# location under /var.  We think that WordFence may be locking up occasionally when wflogs
# is on an NFS mount, and our /var mount is local disk.  It seems to help.
before 'cul:wp:deploy:create_symlinks', 'cul:wp:deploy:symlink_wflogs_to_var_directory'

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/cul/capistrano-cul.

License

The gem is available as open source under the terms of the MIT License.