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
)
cap {env} cul:auto_tag
Tags the current commit as the version number provided in VERSION
.
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
cap {env} cul:wp:setup
Sets up a WordPress docroot and runs deployment; does not install WordPress and does not create any users.
cap {env} cul:wp:install
Runs a WordPress installation for a newly set up instance and creates a new admin user.
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.
cap {env} cul:wp:searchreplace
Runs a search and replace operation on the tables in a WordPress installation.
cap {env} cul:wp:migrate:copy_from
Copies the WordPress installation from one environment to another (e.g. prod to dev)
cap {env} cul:wp:update:core
Updates WordPress core to the latest version.
cap {env} cul:wp:update:plugins
Updates non-repo-managed plugins to the latest version.
cap {env} cul:wp:update:themes
Updates non-repo-managed themes to the latest version.
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.