Get your Kraftwagen started!

First make sure to have Drush installed. Versions 5.x and 6.x are supported. Kraftwagen builds its command line interface on Drush.

Go to the directory where Drush expects extensions — on Unix/OSX this is usually ~/.drush/ — and clone the Kraftwagen Drush extension from GitHub. After this you should clear the drush command cache.

cd ~/.drush
git clone "git://github.com/kraftwagen/kraftwagen.git"
drush cc drush

You can keep your Kraftwagen up-to-date by doing a git pull from its directory.

Per project

We maintain a tool to install Drush and Kraftwagen local to your project. Apart from this link we consider it beyond the scope of this tutorial.

cd ~
mkdir example_project
cd example_project
drush kw-np  # or `drush kw-new-project`

The kw-new-project command will ask some questions — a the project name (both human and machine) and the location of a skeleton repository — after which it will clone the skeleton repository to generate your project files in ~/example_project/src/.

We maintain a basic skeleton repository on GitHub from which you can use (simply fork to create your own skeletons). Take a look at the panopoly branch in our example skeleton to a great example how your own opinionated skeleton could look. You can use this Panopoly skeleton by specifying git://github.com/kraftwagen/skeleton.git as the repository URL and panopoly as the branch to use.

Now the source of the project is created in src/. This is the directory that you would usually want under version control. After this you can skip to the procedure of running the setup.

The source of a Kraftwagen project is a Drupal install profile. Both Drupal core and contributed modules are pulled in using Drush’ own make command and some *.make files. This way your repository only contains your code.

If you have an existing Kraftwagen project under version control you simply create a directory for that project, change to it, and clone/checkout the source code into src/.

cd ~
mkdir example_project
cd example_project
git clone $REPO_URL src

Run setup

cd ~/example_project
drush kw-s  # or `drush kw-setup`

settings.php and settings.local.php

The settings files are copied from the src/cnf/ directory. These files contain target-specific settings for your Drupal installation. Later, when building an actual Drupal installation, these files are symlinked into it.

environment

This file by default contains one word production, it is used to determine which environment we currently run in.

files/

The files/ directory is used to store user uploads. At this point it is empty. Later, when building an actual Drupal installation, it is symlinked into it.

You should change the settings.local.php file to be able to connect to the database. Furthermore, if you want to use the development settings, change the contents of the enviroment file to development.

The source of the project is not a working Drupal installation. It doesn’t even contain Drupal itself. It needs to be build.

cd ~/example_project
drush kw-b  # or `drush kw-build`

A build creates a *.make file out of your src/tools/build.make.tpl ready for consumption by drush make (which is run as part of kw-build). This will copy the content of your src/ directory into profiles/$NAME/, where $NAME is the project key specified in build.make.tpl.

When drush make has finished Kraftwagen will symlink your settings files and files/ directory from cnf/ into the sites/default/ directory of the new build.

Finally Kraftwagen creates of updates a symlink from the directory in builds/ where your new build resides (identified by a timestamp), to build/.

cd ~/example_project/build
drush kw-id   # or `drush kw-initialize-database`

This basically runs drush site-install $PROFILE_NAME. Where Kraftwagen sets $PROFILE_NAME to the basename of the *.info file in the root of src/.

When your code has changed, it is very likely that your database needs to be synchronized to reflect the new code.

Until now, Kraftwagen hasn’t done much more for you than copying some files around and creating some symlinks. All Kraftwagen commands we executed do just that or provide simple convenience wrappers around existing Drush commands. The updating process is a bit different.

cd ~/example_project/build
drush kw-u  # or `drush kw-update`

This basically runs four sub-commands:

1. Apply module dependencies
2. Run hook_update_N implementations
3. Revert all Features
4. Run manifests

Apply module dependencies

Drupal has an excellent way of defining the dependencies of modules. Yet we missed a method to automatically enable all dependencies of an install profile and uninstall all modules that are not required, in a running site (Drupal only takes care of this during installation).

To execute this sub-command by itself:

cd ~/example_project/build
drush kw-amd development  # or `drush kw-apply-module-dependencies development`

An important difference between drush kw-amd and Drupal’s installation process is the support for environment dependencies. As you can see in the code above, we pass the development environment. This instructs drush kw-amd to enable dependencies for the development environment. In *.info files this is specified with:

env_dependencies[development][] = devel

Running hook_update_N implementations

Drupal defines database migrations in hook_update_N functions, which can be run with:

cd ~/example_project/build
drush updatedb

Kraftwagen provides manifests, a versatile which also allows you to write your database migrations. It is recommended to use hook_update_N implementations only for schema migrations, and otherwise use Kraftwagen’s manifests.

Reverting Features

Here we simply use the Drush command that Features exposes to synchronize the database with the defined components.

cd ~/example_project/build
drush features-revert-all

Run manifests

Kraftwagen’s manifests are named (database) migrations that are defined in modules and can be used to synchronize anything that cannot be done with hook_update_N (schema changes) or Features (e.g.: node types, fields, variables, CTools exportables). Manifests are mainly used to create nodes (or other entities) and assign dynamic variables. Manifests need to be idempotent, which means they can safely be executed multiple times.

Manifests are registered in a module’s *.install file using hook_kw_manifests_info(). For example:

/**
 * Implements hook_kw_manifests_info().
 */
function mymodule_kw_manifests_info() {
  return array('my_manifest' => array(
    'callback' => 'mymodule_manifest_define_homepage',
  ));
}

function mymodule_manifest_define_homepage() {
  kw_itemnames_ensure(
    'node', 
    'homepage', 
    array(
      'title' => 'Welcome!', 
    ),
    array(
      'type' => 'page', 
      'language' => LANGUAGE_NONE,
      'body' => array(
        LANGUAGE_NONE => array(array(
          'value' => '
Welcome to my site!
',
          'format' => 'filtered_html',
        ))
      )
    )
  );
}

In this example we use the kw-itemnames module to ensure a certain node is existing.

To be able to use this example, you should add both kw_manifest and kw_itemnames_entity to the dependencies of your module and run drush kw-amd development after that.

In the API documentation of Kraftwagen Manifests the other options are explained. It is for example possible to define that a manifest depends on another manifest and/or limit a manifest to an environment.

The kw-manifests module registers a Drush command to run all manifests. Just like drush kw-amd it accepts the environment as an argument.

cd ~/example_project/build
drush kw-m development  # or `drush kw-manifests development`

Enjoy the ride with Kraftwagen… Any questions or remarks: find us on GitHub!