Getting Started

Installation

Didi is available as a gem via Rubygems

$ gem install capistrano-didi

After installation you will have two new commands at your disposal: "didify" and "didi". The former initializes the configuration for a new drupal project while the latter allows you to execute the different deployment (and other) tasks.

Didify

$ didify
Please specify the directory to didify, e.g. `didify .'

$ didify .
[add] writing './Capfile'
[add] making directory './config/deploy'
[add] writing './config/deploy/staging.rb'
[add] writing './config/deploy.rb'
[done] didified!

WARNING: drupal folder not found! install drupal in folder "drupal" or change the :drupal_path variable.
WARNING: for example: drush dl drupal --drupal-project-rename="drupal"

After editing your config files just run: "didi deploy:cold" to set things up.
After that you can do incremental updates with: "didi deploy"
Or "didi deploy:rebuild" to setup from scratch

The didify tool will create the necessary configuration files for your drupal project.

By default 1 stage will be created called "staging". In this file you put the specific configuration options for that hosting environment. The main "deploy.rb" file contains general setting shared over all the stages.

If your drupal site is located in a folder other than "drupal" you may change the name of the folder in deploy.rb

Didi

If you specify the "-T" parameter all the available tasks will be shown.

$ didi -T
## main tasks
didi deploy                   # Deploys your Drupal site, runs drush:update
didi deploy:update            # Copies your project and updates the symlink.
didi deploy:rebuild           # Deploys latest code and rebuild the database
didi deploy:cold              # Setup a drupal site from scratch

## individual tasks
didi deploy:check             # Test deployment dependencies.
didi deploy:setup             # Prepares one or more servers for deployment.

didi deploy:pending           # Displays the commits since your last deploy.
didi deploy:pending:diff      # Displays the `diff' since your last deploy.

didi deploy:cleanup           # Removes old releases and corresponding DB back...
didi deploy:rollback          # go back to the previous release (code and data...
didi deploy:rollback:code     # Rolls back to the previously deployed version.

didi deploy:update_code       # Copies your project to the remote servers.
didi deploy:symlink           # Updates the symlink to the most recently deplo...

## drush related tasks
didi drush:update             # Update via drush, runs fra, updb and cc
didi drush:cc                 # Clear the Drupal site cache
didi drush:fra                # Revert all enabled feature modules on your site
didi drush:updb               # Apply any database updates required (as with r...
didi drush:si                 # Install Drupal along with modules/themes/confi...

## maintenance tasks
didi manage:block_robots      # Block bots via robots.txt
didi manage:pull_dump         # Dump remote database and restore locally
didi deploy:web:disable       # Present a maintenance page to visitors.
didi deploy:web:enable        # Makes the application web-accessible again.

## different stages
didi staging                  # Set the target stage to `staging'.

## drupal tests used jenkins
didi tests:checksum_core_test # Core hack detection
didi tests:php_lint_test      # Test php lint
didi tests:unit               # Runs unit tests for given site
didi tests:unit_all           # Runs all unit tests for given site

In summary, there are tasks that run other tasks and there are individual tasks. For completeness all tasks are listed above, but in daily use you will only need a few. The "meta" tasks that run others are explained here. If you are unsure about what a task exactly does you can always run it "dry" with the "-n" parameter. This will run the task as usual but without sending the actual commands to the server.

$ didi deploy -n

Examples

You can pick and choose which tasks to include in your workflow by combining them, see samples below.

To update your drupal code and clear the cache on the staging server you would run:

$ didi staging deploy:update drush:cc

This command will build a drupal site from scratch (drush site-install) on the testing server then revert all the drupal features and run simpletests.

$ didi testing deploy:rebuild drush:fra tests:unit

To copy a database form one stage to another

$ didi production manage:pull_dump
$ didi staging manage:push_dump

The pull_dump task will load an sql dump in your the database configured under :local_database. Optionally you may create a .sql file under config/sql/{stage_name}.sql that will be run before restoring the database locally. For example clearing cache tables, removing sensitive information (passwords, email addresses, etc)

Folder Structure

A deploy with didi uses the following folder structure on the remote server.

[deploy_to]
[deploy_to]/releases
[deploy_to]/releases/20120415154742
[deploy_to]/releases/...
[deploy_to]/db_backups
[deploy_to]/shared
[deploy_to]/shared/default/files
[deploy_to]/shared/default/settings.php
[deploy_to]/current -> [deploy_to]/releases/20120415154742

Each time you deploy, a new folder will be created under the "releases" folder. Then, the "current" symlink will be updated to point to that folder.

Within each release folder, the files folder and the settings.php file will be symlinked from the shared folder. This means they should not be part of your repository. Make sure that no drupal module writes files to disk other than to the files folder as they will be gone by the next deploy.

[deploy_to]/current/drupal/sites/default/files -> [deploy_to]/shared/default/files
[deploy_to]/current/drupal/sites/default/settings.php -> [deploy_to]/shared/default/settings.php

You’ll need to make sure you’ve configured your web server to look at [deploy_to]/current/drupal (or other) as the document root for your application.

Configuration files

The main configuration file that is read first is config/deploy.rb

set :default_stage, "staging"
set :stages, %w(staging production)
set :application, "your_application_name"
set :repository,  "your_repository_location_here"
set :drupal_path, "drupal" # change this to your drupal folder

For each environment (called "stages") a different file with specific configuration option should be created. See for example: config/deploy/staging.rb

set :user, "ssh_user_name"
server "server.example.com", :app, :web, :db, :primary => true

set :deploy_to, "/path/on/remote/server"
set :branch, "master"

set :db_type, "mysql"
set :db_name, "database_name" # supports %domain token for multisite
set :db_username, "database_user_name"
set :db_password, "database_password"

set :profile, "minimal"
set :domain, "default" # array for multisite 
set :site, "drupal.example.com" # support %domain token for multisite
set :sitemail, "[email protected]"
set :adminpass, "drupal_admin_pass" # username wil be "admin"

set :baseline, "drupal_feature_to_activate_after_fresh_install"

set :local_database, "database_name" # optional, used with manage:pull_dump
set :push_dump_enabled, false # optional, enables manage:push_dump, default to false (dangerous)

set :enable_robots, false # optional, puts disallow all in robots.txt, defaults to false
set :no_disable, true # optional, puts site in maintenance mode during deploy, defaults to true
set :backup_database, true, # optional, perform db backup during deploy, defaults to true

set :srv_usr, 'www-data' # optional, configure apache user, defaults to www-data