Deploying Bedrock Sites

Bedrock was created with Capistrano as its built-in deployment tool and its remained that way for almost 18 months.

Very soon, the Capistrano specific files and configs in Bedrock will be moved to its own separate repository but still easy to use. You can follow the progress at https://github.com/roots/bedrock/pull/163 and check out the new repo.

At this point the Capistrano configs are considered feature complete and mature. However if updates are needed, that project will still be maintained and always available.

If you still want to use Capistrano with Bedrock, nothing much changes other than having to copy over a few files.

The Replacement

What’s replacing it? Trellis now has deploys built in.

After Trellis was introduced, we quickly realized there was some duplication going on and an opportunity to unify and simplify deployments. Ansible is uniquely suited for deployments as well as a server configuration management tool unlike other tools like Chef and Puppet for example.

The most common argument against Capistrano is its Ruby requirement. Although Ruby is only needed locally on your host computer, it’s still an annoyance to deal with if you only work on WordPress/PHP projects. It’s also harder to customize without any Ruby knowledge.

Now instead of requiring PHP, Python + Ansible, and Ruby + Capistrano, you only need PHP and Python + Ansible (and Python is included by default in Linux and OS X).

We’ve eliminated an entire other language (Ruby), packages (RubyGems), and a dependency manager (Bundler).

Unification

If you were already using Trellis then you’d have to configure your sites and hosts in Ansible and also duplicate that information in your Capistrano configs. All of this configuration belongs in a single place which is Ansible.

Now you only need to configure your Bedrock sites in one place and you’ll get fully integrated deployments out of the box.

The Best Parts of Capistrano

What’s important is that we’ve preserved the best part of Capistrano while keeping it simpler.

Capistrano is known for its great deployment process and directory structure:

├── current -> /srv/www/my_app_name/releases/20150120114500/
├── releases
│   ├── 20150080072500
│   ├── 20150090083000
│   ├── 20150100093500
│   ├── 20150110104000
│   └── 20150120114500
├── repo
│   └── <VCS related data>
└── shared
    └── <linked_files and linked_dirs>

Deploys in Trellis follow the exact same process. It creates a virtually identical directory structure and updates the current symlink to finish the deploy.

Usage

If you’re familiar with Capistrano, then you know it offers these simple commands for deploys and rollbacks:

cap production deploy
cap production deploy:rollback

Deploys with Trellis are just as easy:

./deploy.sh production example.com

The above is using a bash script we provide that wraps the original command:

ansible-playbook -i hosts/<environment> deploy.yml --extra-vars="site=<site name>""

Rollbacks are also supported with a single command:

ansible-playbook -i hosts/<environment> rollback.yml --extra vars="site=<site name>"

Hooks

The one advantage Capistrano has over Ansible deploys is its flow with hooks.

With Capistrano you can just install another Gem to add an extension such as running Composer during a deploy.

Our Ansible deploys don’t expose hooks in the same way, but we do have set places where you can run arbitrary commands:

  • pre build
  • post build
  • post finalize

The following variables are available:

  • pre_build_commands_local
  • pre_build_commands
  • post_build_commands
  • post_finalize_commands

Here’s a common example of compiling assets during post build:

project_post_build_commands:
  - path: web/app/themes/mytheme
    cmd: npm install && gulp --production

Each command takes a cmd (command) and an optional path (defaults to project root).

That command above would run on the remote server.

Customization

The big advantage to our new Ansible deploys is that you can just modify the deploy role to fit your needs. Capistrano was a vendored Gem so you couldn’t modify its source (and wouldn’t want to anyway). With Trellis, you always have control over the source and it’s meant to be modified.

Read the discussion on our Discourse

Get our latest updates & occasional tips on building better WordPress sites

Follow @rootswp on Twitter