This blog/tutorial explains how to convert your website to a Drupal profile which can be deployed using Kraftwagen. This will help you create and maintain a professional website and optimize your workflow.What?

Kraftwagen is a drush extension containing a set of Drupal modules enabling you to get a tighter grip on the distribution and subsistence of your (or your customer’s) website.

With Kraftwagen you can easily set up multiple environments like development, staging and production. It also lets you store configuration settings in your code instead of your database saving you a vast amount of time setting up a new environment. This feature enhances the use of version control so every update can be traced or restored.

Another great feature is the ability to maintain third party code like modules and libraries. You tell Kraftwagen which modules you need and it will download and install them for you. New version? No problem, just change the version number.

How does it work?

Your entire website is stored in a profile. Forget Drupal core and the sites folder. This profile contains your custom modules, your theme and configuration settings. So far nothing new on the horizon.

There are three files that make the magic happen:

• The make file (your_site.make), which defines all the contrib modules and libraries you want to download. Drush handles this, so still no Kraftwagen involved here.
• The info file (your_site.info), which defines what modules must be enabled. Just a standard Drupal file.
• In addition to the previous files, Kraftwagen adds the build.make.tpl, which provides a template for your make file. It defines your profile and Kraftwagen directory, which Drupal version you want to use and optionally which patches you want to apply to it. 

If all files are in place and you are satisfied with your configuration, you just give the build command and wait. Drupal core will be installed along with all your modules and settings. When the build is done, all you have to do is give the update command and you’re good to go.

Easy as pie.

How to start?

Visit http://kraftwagen.org/get-started.html and install Kraftwagen. You’ll also find some instructions here on setting up a new project or update an existing project.

But what if you want to convert your existing non-Kraftwagen site to a Drupal profile? That’s what we will be covering in the following paragraphs.

To Kraftwagen and beyond!

First, create a new Kraftwagen folder because we will create a fresh installation of your site. Now, run the drush command drush kw-np (or drush kw-new-project) inside that folder and enter a human name (like Your Site) and machine name (like your_site). You can just press enter when asked for a skeleton and branch.

You’re folder structure should look like this:

kw/ src/   cnf/   modules/   themes/   tools/   translations/   .gitignore   README.md   your_site.info   your_site.install   your_site.make   your_site.profile

We’ve got ourselves an empty Drupal profile here. Time to merge your existing site in here.

Specify your desired Drupal core version in tools/build.make.tpl in this line:

projects[drupal][version] = "7.23"

Congratulations! You’ve just upgraded your site!

Next, copy all your custom modules to modules/custom/. Now, assuming you don’t know all the contrib modules you’ve been using from the top of your head, we will generate a list from your existing site.

Go to the root directory of your existing site and run drush make-generate. Drush generates a make file with all the modules you have installed. Open it and copy this list into your_site.make in your Kraftwagen folder. Notice that there are already some modules prefilled. If you don’t need them, you can erase all modules except the Kraftwagen modules (starting with kw_).

Next up is checking which modules are enabled in your existing site. Again, go the the root of your existing site and run drush pm-list --type=Module --status=enabled.

Unfortunately, this list is not as user friendly as the generated make file. Copy it and paste it into your_site.info in your Kraftwagen folder. Convert every line to:

dependencies[] = modulename

Preferably grouped and sorted by core, contrib, custom and optionally features. You may remove the prefilled dependencies except for the Kraftwagen ones. You’ll notice there are also env_dependencies, these enable the given module only when the defined environment (like development or staging) is set.

Now the modules part is done, copy your theme folder to src/themes/.

As the final part of the setup, navigate to the src directory and run drush kw-s (or drush kw-setup). When you navigate to the parent directory, you’ll find two new folders: builds and cnf.

Every time you make a build, it will be stored in the builds folder. The foldername always matches the date and time of creation, for example: 20150125-135919 (2015-01-25 13:59:19). Every build gets it’s own directory so remember to remove some old builds in a while to save some space.

The cnf folder holds your settings file and files directory. The environment file defines in what kind of environment you’re working, this would be development, staging or production. Open up settings.local.php and set your database info. Also make sure the files directory is writable and has the correct ownership and permissions. The Drupal handbook provides a useful script which handles this for you, you’ll find it at the bottom of this article: https://www.drupal.org/node/244924.

Build it!

Duplicate your database so we don’t overwrite the existing one. Always make a backup of your database before you make a new build.

Navigate to the src directory and run drush kw-b (or drush kw-build). This will download Drupal core and all contrib modules specified in the make file and copy your custom stuff in site/profiles/your_site/.

It also creates symlinks in site/sites/default/ to the settings.php and files folder in your cnf directory. When the build is finished, a symlink build is created to the newly created build in the builds folder so you don’t need to remember the full build name (20150125135919) and to switch easily between build folders if necessary.

So when the build is successful, you can find your profile in an entire Drupal installation in kw/build/.

Adapt your database

Making a build is not enough. We need to tell our database some major stuff is going on in here. Navigate to kw/build/. Normally, drush kw-u (or drush kw-update) would be sufficient. This enables the modules specified in the info file, executes module updates, reverts all features and runs manifests. All in one command.

However, since this is the first time we’ve made a build from a converted website, we need to do some more.

First, we need to tell our database what profile and theme should be used. This can be achieved by executing the following SQL queries:

UPDATE variable SET value = 's:9:"your_site";' WHERE name = 'install_profile'; UPDATE variable SET value = 's:10:"your_theme";' WHERE name = 'theme_default';

Note that the value is a serialized string, so the number in 's:9' should be the character count of 'your_site'. The same goes for 'your_theme'.

Manually clear the cache with:

TRUNCATE `cache`; TRUNCATE `cache_block`; TRUNCATE `cache_bootstrap`; TRUNCATE `cache_field`; TRUNCATE `cache_filter`; TRUNCATE `cache_form`; TRUNCATE `cache_image`; TRUNCATE `cache_menu`; TRUNCATE `cache_page`; TRUNCATE `cache_path`; TRUNCATE `cache_token`; TRUNCATE `cache_update`; TRUNCATE `cache_views`; TRUNCATE `cache_views_data`;

Then we need to update the registry by running drush rr (or drush registry-rebuild). This is necessary because all contrib and custom modules have moved from sites/all/modules/ to profiles/your_site/modules/.

Now, as finishing touch, we can run drush kw-u.

You may need to clear the cache (drush cc all), point your browser to kw/build/ and you’re good to go.

Conclusion

You’ve just turned your website into an easily manageable and deployable Drupal profile.

Need to add a new module? Just add it to your make file and make a new build. Module update? Just change the version number and make a new build. Or do you want to add a staging environment for your customer to check things out? Make a new copy of your Kraftwagen folder (or clone it if you’re using git), change the environment variable to staging and start building.

You should also notice that basically, the contents of kw/src/ folder are copied to site/profiles/your_site/, which means that if you are using git, you can happily code further in the profiles directory.

There are lots of useful things you can do with Kraftwagen. First get comfortable with the build procedure, then you should also check out manifests and the way patches are handled.

For now, as stated in the conclusion at Kraftwagen.org: Enjoy the ride with Kraftwagen...