Rocketeer is a php application which takes care to cover all the aspects of deploying a web site from a local environment to a production environment.

This article is focused on the configuration and the usage of Rocketeer to deploy a Grav website. In order, to use this application, you need to:

  1. Have a basic Git knowledge
  2. Maintain your website under Git Version Control System
  3. Have an SSH connection on your remote server

You can read about those requirements on the first part of a serie of articles about websites deploying.

Rocketeer is heavily inspired by Capistrano, a very famous remote server automation and deployment tool written in Ruby, from which takes inspiration, in particular, for the directory structure deployed to the remote server.

Basically it creates a structure like this one:

| remote-server-path
    |-- my-app
        |-- current => /var/www/facebook/releases/20130721000000
        |-- releases
        |  |-- 20130721000000
        |  |  |-- app
        |  |     |-- storage
        |  |       |-- logs => /var/www/facebook/shared/app/storage/logs
        |  | 20130602000000
        |-- shared
          |-- app
            |-- storage
              |-- logs

The application my-app is stored under the remote-server-path and it is made by three folders:

  1. Current, a symlink to the latest releases
  2. Releases, where are kept the latest 4 releases
  3. Shared a folder where you can share objects through the website releases

Install and configure Rocketeer

Rocketeer is distributed as an executable phar file and does not require nothing to install on the remote server.

To install the application, just run these commands:

$ wget http://rocketeer.autopergamene.eu/versions/rocketeer.phar
$ chmod +x rocketeer.phar
$ mv rocketeer.phar /usr/local/bin/rocketeer

You are now able to run the rocketeer command from anywhere on your computer.

Open a console and move under the root folder of the application you want to deploy and run the following command to configure rocketeer:

rocketeer ignite

A wizard will prompt you several questions required to configure the connection with your remote server.

When you finished, Rocketeer creates a .rocketeer directory under your project folder where are stored the application configuration files.

Next, you should check the connection is properly configured, running this command:

rocketeer check

If everything works fine you are ready to deploy your application, otherwise you should verify that the information provided are correct. The connection information are saved in the config.php file, so just open it and verify that everything is fine.

return [

    [...]

    'connections'      => [
        'production' => [
            'host'      => 'IP address',
            'username'  => 'user',
            'password'  => '',
            'key'       => '/home/user/.ssh/id_rsa',
            'keyphrase' => '',
            'agent'     => '',
            'db_role'   => true,
        ],
    ],

I've noticed that providing the host using the DNS name might not work. If you fall in this situation, you just need to provide the IP address instead the DNS.

Now you should verify the remote server configuration. By default Rocketeer uses as remote path the folder var/www and this is something you have to change mostly when you are on a shared hosting.

The remote server configuration is handled by the remote.php file and this configuration is handled by the root_directory option, you just need to configure it to fit your needs:

return [
    [...]

    'root_directory' => '/home/user/example.com',

Environments

Now we must decide how we want to structure our application. Thanks to Dreamhost's sub-domains, I will explain how to configure Rocketeer to deploy the website on two environments: stage and production. In this way I will have a stage environment, handled by a sub-domain, where I will be able to deploy and check that everything works fine before go to production.

This configuration is defined in the stages.php file, reported below and stripped by comments:

<?php

return [
    'stages'  => ['stage', 'production'],
    'default' => 'production',
];

I defined my environments, calling them stage and production, I did this configuration changing the stages option. At last, I told Rocketeer to use the production environment as default.

This configuration will produce this directory structure, on the remote server:

| remote-server-path
    |-- my-app
        |-- production
            |-- current
            |-- releases
            |-- shared
        |-- stage
            |-- current
            |-- releases
            |-- shared

So my domain will be configured to point the remote-server-path/my-app/production path, while the stage sub domain will be configured to point the remote-server-path/my-app/stage path.

Hooks

At last, we must be sure to provide a clean environment after each deploy, so we will configure the hooks.php file to clean the cache, the assets and images folders, after each new release has been created or after a new update has been requested.

In this file you can define commands to be run on the server before and after you run a Rocketeer task, like setup or deploy.

The operations mentioned above must be run after a deploy is completed, so we will configure the after section as follows:

[...]
'after'  => [   
    'setup'   => [],
    'deploy'  => [
        '0' => 'rm -rf ./cache',
        '1' => 'rm -rf ./images/*',
        '2' => 'rm -rf ./assets/*',
    ],
    'update'  => [
        '0' => 'rm -rf ./cache',
        '1' => 'rm -rf ./images/*',
        '2' => 'rm -rf ./assets/*',
    ],
    'cleanup' => [],
],

This configuration tells Rocketeer to remove the cache folder and to clean the images and assets folder, every time a deploy or update command are run. I could have run the bin/grav clear-cache command instead of removing cache and assets, but this could cause issues with permissions, so I preferred removing them manually.

Please note that the Rocketeer update command was not set by default in the hooks.php file, so I added it by hand.

Awesome, but I also would like that the stage environment is not indexed by search engines. My solution consists in providing a robots file for stage and production environments and then rename the right file basing this operation on the corresponding environment, when I did a deploy.

This configuration is quite simple. I just need to add a stages folder under the .rocketeer directory. Next, I need to create a folder for each environment and add a different hooks.php file under each of those folders. Here it is the file system structure:

| .rocketeer
    |-- stages
        |-- production
            |-- hooks.php
        |-- stage
            |-- hooks.php

Now I update the production/hooks.php as follows:

'deploy'  => [
    [...]
    '3' => 'mv robots.prod robots.txt',
],

and the stage/hooks.php as follows:

'deploy'  => [
    [...]
    '3' => 'mv robots.stage robots.txt',
],

Obviously the .rocketeer/hooks.php file must be removed.

Avoid running Composer after git repository clone

At last Grav comes with all Composer vendors installed, so you might have saved them into your repository. If you are in this situation, you must disable the Composer execution, called each time the site is deployed or updated.

To accomplish this task, just open the strategies.php file, locate the composer section, which should look like this one:

'composer'     => [
    'install' => function (Composer $composer, $task) {
        return $composer->install([], ['--no-interaction' => null, '--no-dev' => null, '--prefer-dist' => null]);
    },
    'update'  => function (Composer $composer) {
        return $composer->update();
    },
],

then change it as follows:

'composer'     => [
],

Your configuration is completed, so you can prepare the remote structure folders just running this command:

rocketeer setup

Now you can deploy your website for the production environment as follows:

rocketeer deploy

and as follows for the stage environment:

rocketeer deploy --stage="stage"

To learn more about this awesome tool, you can read the full documentation at Rocketeer website and give a look to this nice general intro guide.

Next Post Previous Post

Related Posts