capistrano-wp 0.4.2 → 0.4.3

data/README.md

@@ -11,27 +11,239 @@ also deploy multisite environments with WP at the root).
 
 ## Usage
 
-See `doc/examples` for an example Capfile and capistrano config directory.
+This is a plugin for the Capistrano deployment tool.  If you are unfamiliar
+with Capistrano, we would suggest at least familiarizing yoruself with
+the general concepts outlined in the [Capistrano Wiki](https://github.com/capistrano/capistrano/wiki).
 
-General Capistrano usage:
+### Assumptions (Requirements)
+
+  - Your code repository is your webroot
+
+### Install / Setup
+
+    gem install capistrano-wp
+    cd /path/to/repository
+    capify-wp .
+
+### Abridged General Capistrano Usage
 
 1. Create a user for deploying your WordPress install
 2. Create an SSH key for the deploy user, and make sure you can SSH to it from your local machine
 3. [Install RubyGems][rubygems].  Crowd Favorite prefers to use [RVM][rvm] to maintain ruby versions, rubygems, and self-contained sets of gems.
 4. Install the capistrano-wp gem (which will install Capistrano and friends): `gem install capistrano-wp`
-5. Ensure that your project is in a repository starting at the web root
-6. Copy the example configuration (from doc/examples) into the root of your repository, and customize as appropriate
-7. Make sure your `:deploy_to` path exists and is owned by the deploy user
-8. Run `cap deploy:setup` to set up the initial directories
-9. Run `cap deploy` to push out a new version of your code
-10. Update your web server configuration to point to the current-release directory (in the `:deply_to` directory, named `httpdocs` by default)
-11. Relax and enjoy painless deployment
+5. Follow **Install / Setup** steps above
+6. Make sure your `:deploy_to` path exists and is owned by the deploy user
+7. Run `cap deploy:setup` to set up the initial directories
+8. Run `cap deploy` to push out a new version of your code
+9. Update your web server configuration to point to the current-release directory (in the `:deply_to` directory, named `httpdocs` by default)
+10. Relax and enjoy painless deployment
 
-[rubygems]: http://rubygems.org/pages/download
-[rvm]: https://rvm.io/
+## Capistrano Multi-stage
+
+This deployment strategy comes with multi-stage support baked in.
+
+For documentation regarding this portion of functionality, see the
+[Capistrano Multistage Documentation](https://github.com/capistrano/capistrano/wiki/2.x-Multistage-Extension).
+
+## Capistrano-WP Specific Features
+
+### Handling of WordPress
+
+This gem handles WordPress via SVN directly from WordPress.org.
+
+In your main `config/deploy.rb` file you will see how to decalare what
+version of WordPress you wish to use by defining an SVN location
+like `branches/3.6`, `tags/3.6.1` or even `trunk`
+
+```ruby
+set :wordpress_version, "branches/3.5"
+```
+
+It then places WordPress where you declare it to live within the stage
+specific configuration files, for example `config/deploy/production.rb`
+
+```ruby
+set(:wp_path) { File.join(release_path, "wp") }
+```
+
+This places WordPress in a directory called "wp" within your webroot.
+
+It also gracefully handles the situation where both your code repository
+and WordPress live at the webroot
+
+This process enables you to not have to track WordPress within your code repository.
+
+### Persistent file/directory symlinks
+
+This gem augments the way capistrano handles directories you need to "persist"
+between releases.  Providing a declaritive interface for these items.
+
+There are some common directories that WordPress needs to act this way.  By
+default, if the following directories exist in the "shared" directory, they
+will be symlinked into every release.
+
+  - `cache` is linked to `wp-content/cache`
+  - `uploads` is linked to `wp-content/uploads`
+  - `blogs.dir` is linked to `wp-content/blogs.dir`
+
+This is the way these would be declared, either in the main `config/deploy.rb` or
+in your stage specific files, if they weren't defaults
+
+```ruby
+set :wp_symlinks, [{
+  "cache" => "wp-content/cache"
+  "uploads" => "wp-content/uploads"
+  "blogs.dir" => "wp-content/blogs.dir"
+}]
+```
+
+These will happen without any further configuration changes.  If you wish
+to override any of these defaults, you can set the target of the link to `nil`
+
+```ruby
+set :wp_symlinks, [{
+  "cache" => nil
+}]
+```
+
+This would turn off the default `cache` symlink
+
+You can easily add your own project (or even stage) specific links
+
+If you have a `customlink` directory in the shared directory, you can add
+a custom link like so.
+
+```ruby
+set :wp_symlinks, [{
+  "customlink" => "wp-content/themes/mytheme/customlinktarget"
+}]
+```
+
+### Persistent Configs
+
+These are handled almost identically as above except they are copied
+from the shared directory instead of symlinked.
+
+This is primarily for config files that are sometimes written
+to by plugins.  In some cases when php tries to write to a symbolic
+link, the link is destroyed and becomes a zero byte file.
+
+By default the following copies are attempted
+
+```ruby
+set :wp_configs, [{
+  "db-config.php" => "/",
+  "advanced-cache.php" => "wp-content/",
+  "object-cache.php" => "wp-content/",
+  "*.html" => "/",
+}]
+```
+
+You can follow the same steps as the symlinks for modification or addition
+to the default config copying rules.
+
+### Stage specfiic overrides
+
+Stage specific overrides allow you to target specific configuration
+files to their respective stage.
+
+You need to use a specific set of `.htaccess` rules for production.
+
+If you place a file named `production-htaccess` in your `config/` directory
+
+and add it to your `:stage_specific_overrides` in your `config/deploy/production.rb`
+
+```ruby
+set :stage_specific_overrides, {
+  ".htaccess" => ".htaccess"
+}
+```
+
+This will place the proper `production-htaccess` file in the root of
+your next release, overriding any existing file of the same name.
+
+By default, it looks for the common `.htaccess` situation
+along withh `local-config.php`
+
+```ruby
+set :stage_specific_overrides, {
+  "local-config.php" => "local-config.php",
+  ".htaccess" => ".htaccess"
+}
+```
+
+Modifications and additions are handled similarly to symlinks and
+configs, but note the lack of a wrapping `[]`
+
+### Stripping out unnecessary files and directories
+
+You can remove specific files and directories from your releases
+at the time of deploy.
+
+By default the list of things the gem strips out looks like this
+
+```ruby
+set :copy_exclude, [
+  ".git",
+  "Capfile",
+  "/config",
+  "capinfo.json",
+  ".DS_Store",
+]
+```
+
+This excludes the listed files from making it into a release
+
+**For this you actually need to re-declare the set to add / remove these exclusions.**
+
+For example, to allow the `.git` directory to exist in the releases, you would
+re-declare the option completely.  Removing the `.git` entry.
+
+```ruby
+set :copy_exclude, [
+  "Capfile",
+  "/config",
+  "capinfo.json",
+  ".DS_Store",
+]
+```
+
+This is usually placed in `config/deploy.rb` but can also be placed at the stage level.
+
+### Detecting Local Changes
+
+This gem by default checks the current release for modifications since
+it was deployed.  Either you're dealing with clients that like to make
+changes in production, or you have plugins that write configs and other
+things to the file system.  This step protects you against moving changes
+that have happend in the target stage out of use.
+
+When deploying, if it detects a change it will stop the deploy process, and
+provide you with a listing of all the files that have been either added,
+changed, or deleted.
+
+At this point you can rectify the changes yourself if you wish, adding them to
+your source control, or verifying you don't need them.
+
+Then you call the deploy like this to force it to create the new release.
+
+    cap cf:localchanges:allow_differences deploy
+
+This will tell the deploy to ignore any of these changes and proceed.
+
+If you would like to turn this feature off, you can have it force this by
+default with the following option set in either your main `config/deploy.rb`
+or your stage specific files.
+
+```ruby
+set :snapshot_allow_differences, true
+```
 
 ## Development
 
+[rubygems]: http://rubygems.org/pages/download
+[rvm]: https://rvm.io/
+
 	gem install bundle
 	bundle install
 	rake install

data/VERSION

@@ -1 +1 @@
-0.4.2
+0.4.3

data/bin/capify-wp

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'fileutils'
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{File.basename($0)} [path]"
+
+  opts.on("-h", "--help", "Displays this help info") do
+    puts opts
+    exit 0
+  end
+
+  begin
+    opts.parse!(ARGV)
+  rescue OptionParser::ParseError => e
+    warn e.message
+    puts opts
+    exit 1
+  end
+end
+
+if ARGV.empty?
+  abort "Please specify the directory to capify, e.g. `#{File.basename($0)} .'"
+elsif !File.exists?(ARGV.first)
+  abort "`#{ARGV.first}' does not exist."
+elsif !File.directory?(ARGV.first)
+  abort "`#{ARGV.first}' is not a directory."
+elsif !File.writable?(ARGV.first)
+  abort "`#{ARGV.first}' is not writable by you."
+elsif ARGV.length > 1
+  abort "Too many arguments; please specify only the directory to capify-wp."
+end
+
+def template_dir()
+  t = ["#{File.dirname(File.expand_path(__FILE__))}/../lib/capistrano/templates",
+       "#{Gem::Specification.find_by_name("capistrano-wp")}/lib/capisrano/templates"]
+  t.each { |dir| return dir if File.readable? dir }
+  raise "Paths invalid: #{t}" if not File.readable? t
+end
+
+base = ARGV.shift
+templates = template_dir()
+
+Dir.glob("#{templates}/**/*").each do |file|
+  target = file.gsub(templates, "")
+  next if target.empty?
+
+  target = File.join(base, target)
+
+  if File.exists? target
+    warn "[skip] '#{target}' already exists"
+  elsif File.exists? target.downcase
+    warn "[skip] '#{target.downcase}' exists, which could conflict with `#{target}'"
+  else
+    if File.directory? file
+      puts "[add] making directory '#{target}'"
+      FileUtils.mkdir_p(target)
+    else
+      puts "[add] writing '#{target}'"
+      FileUtils.cp file, target
+    end
+  end
+end
+
+puts "[done] capify-wped!"

data/capistrano-wp.gemspec

@@ -5,12 +5,13 @@
 
 Gem::Specification.new do |s|
   s.name = "capistrano-wp"
-  s.version = "0.4.2"
+  s.version = "0.4.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Crowd Favorite"]
-  s.date = "2013-07-15"
+  s.date = "2013-09-25"
   s.description = "Recipes for deploying and maintaining remote WordPress installations with\nCapistrano.  Pulls in WordPress from SVN, optionally using a local or\nremote cache, and supports a number of common operations and tasks towards\nthe care and feeding of sites that may not be 100% maintained through\nversion control.\n"
+  s.executables = ["capify-wp"]
   s.extra_rdoc_files = [
     "LICENSE.txt",
     "README.md"
@@ -23,6 +24,7 @@ Gem::Specification.new do |s|
     "README.md",
     "Rakefile",
     "VERSION",
+    "bin/capify-wp",
     "capistrano-wp.gemspec",
     "doc/examples/Capfile",
     "doc/examples/config/deploy.rb",
@@ -31,6 +33,9 @@ Gem::Specification.new do |s|
     "doc/examples/config/staging-local-config.php",
     "lib/capistrano-wp.rb",
     "lib/capistrano/crowdfavorite/wordpress.rb",
+    "lib/capistrano/templates/Capfile",
+    "lib/capistrano/templates/config/deploy.rb",
+    "lib/capistrano/templates/config/deploy/production.rb",
     "lib/crowdfavorite.rb",
     "lib/crowdfavorite/support/capistrano_extensions.rb",
     "lib/crowdfavorite/support/namespace.rb",

data/lib/capistrano/templates/Capfile

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'railsless-deploy'
+require 'crowdfavorite/wordpress'
+load 'config/deploy' # remove this line to skip loading any of the default tasks
+

data/lib/capistrano/templates/config/deploy.rb

@@ -0,0 +1,26 @@
+set :stages, %w(production)
+set :default_stage, "production"
+
+require 'capistrano/ext/multistage'
+
+#=============================================================================
+# app details and WordPress requirements
+
+# tags/3.5.1, branches/3.5, trunk
+set :wordpress_version, "trunk"
+set :application, "my-wordpress-site.com"
+
+#=============================================================================
+# app source repository configuration
+
+set :scm, :git
+set :repository, ""
+set :git_enable_submodules, 1
+#set :git_shallow_clone, 1
+
+#=============================================================================
+# Housekeeping
+# clean up old releases on each deploy
+set :keep_releases, 5
+after "deploy:create_symlink", "deploy:cleanup"
+

data/lib/capistrano/templates/config/deploy/production.rb

@@ -0,0 +1,80 @@
+set :stage, "production"
+
+set :user, 'deployuser'
+set :use_sudo, false
+
+server '0.0.0.0', :app, :web, :db, :primary => true
+
+## For multiple server setups
+#
+# server '0.0.0.0', :app, :web, :primary => true
+# server '0.0.0.0', :app, :web
+# # Don't push code to this server with 'cap deploy'
+# server '0.0.0.0', :db, :no_release => true
+
+# Site base directory
+set :base_dir, "/var/local/www/example"
+set :deploy_to, File.join(fetch(:base_dir))
+
+# Webroot
+set :current_dir, "httpdocs"
+
+# Path to WordPress, supports WP at the root (empty string) and WordPress
+# in a custom location (webroot/wp in our example).
+set(:wp_path) { File.join(release_path, "wp") }
+
+# Deploy strategy - use :remote_cache when possible, but some servers need :copy
+#set :deploy_via, :copy
+set :deploy_via, :remote_cache
+
+# Specify a git branch to deploy
+# 
+# Using fetch() here allows you to set your branch from the command line,
+# but allows a default, "master" in this case.
+#
+#    cap deploy -s branch=my-custom-branch
+#
+set :branch, fetch(:branch, "master")
+
+#=============================================================================
+# Files to link or copy into web root from capistrano's shared directory
+# Symlinks are symlinked in
+
+# wp_symlinks defaults to:
+#  "cache" => "wp-content/cache"
+#  "uploads" => "wp-content/uploads"
+#  "blogs.dir" => "wp-content/blogs.dir"
+#
+# To override, set the target to nil:
+#
+#set :wp_symlinks, [{
+#  "cache" => nil
+#}]
+#
+# Or add other files:
+#
+#set :wp_symlinks, [{
+#  "authcache" => "wp-content/authcache"
+#}]
+#
+# Configs are copied in, and default to:
+#  "db-config.php" => "/",
+#  "advanced-cache.php" => "wp-content/",
+#  "object-cache.php" => "wp-content/",
+#  "*.html" => "/",
+#
+# To override (like wp_symlinks):
+#set :wp_configs, [{
+#}]
+#
+# Stage-specific overrides are copied from the config directory,
+# like production-example.txt or staging-example.txt
+# Default list:
+#
+#       "local-config.php" => "local-config.php",
+#       ".htaccess" => ".htaccess"
+#
+# To override or add other files (as above, but note no []):
+#
+#set :stage_specific_overrides, {
+#}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-wp
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-15 00:00:00.000000000 Z
+date: 2013-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capistrano
@@ -168,7 +168,8 @@ description: ! 'Recipes for deploying and maintaining remote WordPress installat
 
 '
 email: 
-executables: []
+executables:
+- capify-wp
 extensions: []
 extra_rdoc_files:
 - LICENSE.txt
@@ -181,6 +182,7 @@ files:
 - README.md
 - Rakefile
 - VERSION
+- bin/capify-wp
 - capistrano-wp.gemspec
 - doc/examples/Capfile
 - doc/examples/config/deploy.rb
@@ -189,6 +191,9 @@ files:
 - doc/examples/config/staging-local-config.php
 - lib/capistrano-wp.rb
 - lib/capistrano/crowdfavorite/wordpress.rb
+- lib/capistrano/templates/Capfile
+- lib/capistrano/templates/config/deploy.rb
+- lib/capistrano/templates/config/deploy/production.rb
 - lib/crowdfavorite.rb
 - lib/crowdfavorite/support/capistrano_extensions.rb
 - lib/crowdfavorite/support/namespace.rb