First steps with dkdeploy-typo3-cms

alt

A couple of days ago we at dkd Internet Service GmbH released dkdeploy-typo3-cms as open source.

dkdeploy-typo3-cms is a plugin for the Ruby-Gem Capistrano which extends the Rake DSL with methods specifically to run commands on servers. Perfectly suited for remote server automation and deployment.

This blogpost will guide you through your first steps on setting up and deploying a TYPO3 CMS Introduction package.

For your convenience we created an example project on GitHub you should use to get started unless you consider yourself familiar with Capistrano.

We will use Composer to install TYPO3 CMS 7.6 LTS, the official Introduction Package and TYPO3 Console from Helmut Hummel.

Prerequisite

The following software should be installed on your development machine.

  • Ruby => 2.1.2
  • Bundler => 1.12.x
  • PHP => 5.5.x
  • Composer => 1.2.0

The destination host (the machine you want to deploy to) should meet the requirements to run TYPO3 CMS and have SSH and a Database installed and configured.

Installation

github

Fire up a terminal session, clone the before mentioned example from GitHub and cd into the project directory.

Verify that bundler is in place:
bundler -v

Run bundle install to install dkdeploy-typo3-cms and its dependencies.
Now verify all Gems have been installed successfully and Capistrano tasks are ready:
bundle exec cap -T will give you an overview of all available tasks.

dkdeploy tasks

Next we will install the TYPO3 source, the introduction package and typo3_console via composer composer -d=htdocs/ install. Depending on how you did install Composer invoking Composer might be different on your machine.
Composer will also run two scripts after it dumped its autoload file.

One will copy a predefined LocalConfiguration.php file from the projects config-folder to its expected destination inside typo3conf/.
The second script will trigger typo3_console to generate a PackageStates.php file.

Deployment

Configuration

Navigate in your shell to config/deploy/dev.rb and adjust server settings as well as deployment path and deployment_user to your own needs.

Another place where you have to tweak some settings is config/deploy.rb.
Go there and find a section # Set file access. Here you can set user and group according to your needs.

It's important to make sure the user running the deployment has sufficient rights on the destination host and that his public ssh key is known to the host.

Setup

The first deployment of TYPO3 CMS requires a few setup steps. These have to be triggered only once, no subsequent actions needed, unless you want to change settings.
dkdeploy-typo3-cms provides tasks for each of these steps:

bundle exec cap dev typo3:cms:create_db_credentials asks for Database credentials and stores these outside the Webroot on your host in a directory named shared/config.

bundle exec cap dev typo3:cms:create_encryption_key_file stores an Encryption Key File in the directory mentioned above.

Same is true for the Install Tool password:
bundle exec cap dev typo3:cms:create_install_tool_password_file

During deployment these files will be referenced with PHPs include() in AdditionalConfiguration.php.

Optionally you can add a default structure as well as some default content to your database by calling:

bundle exec cap dev db:add_default_structure

bundle exec cap dev db:add_default_content

Deployment

Finally you are ready to run your first deployment:
bundle exec cap dev deploy

deployment

Create an admin user:
bundle exec cap dev typo3:cms:add_admin_user[typo3_username,typo3_password]

Done. Your TYPO3 Installation is now ready for your pleasure.

The end

That's all it takes to create a project which provides everything you need to deploy TYPO3 CMS to whatever destination host.
Of course there is a lot more you can do and automate with dkdeploy-typo3-cms, but this would be out of the scope of this post and will be a topic of subsequent posts.

For further information visit our dkdeploy documentation site

Enjoy
~Peter