Hermes

"Hermes is considered a god of transitions and boundaries. He is described as quick and cunning, moving freely between the worlds of the mortal and divine." (Wikipedia)

---

• Gettings started
• Requirements
• Installation
• Configuration
• Artisan Commands
  • Setup
  • Deploy
  • Task
• Built-in Tasks
• Extending Hermes
  • Custom Tasks
  • Custom Routines

---

Getting Started

The Hermes package allows to automate the deploy process via Git on SSH to one or more remote server. It also provides a fully extendable list of automated tasks that can be run on the servers during the deploy process or on demand.

Requirements

In order to work, Hermes needs Git and SSH available in your local environment, as well as all the SSH keys that are required to access the remote servers.

Installation

First of all, add this package to your project via Composer. Require the package in the dev section of your composer.json.

"require-dev": {
    "fsavina/hermes" : "1.1.*"
}

and update the Composer dependencies from your terminal:

composer install

Add the Service Provider to the list of providers in your config/app.php:

'providers' => [
    // ...
    Hermes\HermesServiceProvider::class,
    // ...
],

and complete the installation publishing the laravelcollective/remote package default configuration file:

php artisan vendor:publish --provider="Collective\Remote\RemoteServiceProvider"

Configuration

Since this package uses the laravelcollective/remote package to operate on the remote servers, you need to extend your remotes configurations in the config/remote.php configuration file.

In order to automatically deploy your code to a remote server you need to set the following values:

'stage' => [
    ...
    // laravelcollective/remote config
    ...

    'remote'     => 'stage',
    'root'       => '/path/to/project/root',
    'repository' => '/path/to/remote/repository.git',
    'sudo'       => true,
    'tasks'      => ['composer:install', 'cache:clear'],
    'commands'   => [
        'mkdir /some/dir/foo/bar'
    ]
],

The remote value is the name of a local Git remote pointing to the remote repository on the target server. It can be either an existing remote or it can be created via the setup command.

The root value is the complete path to the target folder for your project on the remote server.

The repository value is the complete path to the gateway Git repository on the remote server.

The sudo value forces the tasks and the commands to be run with super user privileges on the remote server.

The tasks array is the list of built-in or custom tasks that you want to execute every time that the code si transfered to the remote server (eg. install new packages, clean up the cache).

The commands array is optional and can contain a list of shell commands to be executed after both the code transfering and the tasks execution.

For the basic remote configuration to access the remote server via SSH see the laravelcollective/remote website.

Artisan Commands

For more information about the following commands use the -h option to see the Help information and all the available options in your terminal.

Setup

Use the setup command to automatically setup both the local and the remote environments in order to run the deploy system.

php artisan hermes:setup stage

Note: run the Setup command without the remote name to see a list of the available remotes/groups.

Deploy

The deploy commands transfers the project to the given remote server and runs the configured list of tasks and commands.

php artisan hermes:deploy stage

Note: run the Deploy command without the remote name to see a list of the available remotes/groups.

Task

The task commands runs a single task on the given remote server.

php artisan hermes:task stage cache:clear

Note: run the Task command without the remote or task name to see a list of the available options.

Built-in Tasks

The Hermes package comes with a built-in Routine Driver optimized for Laravel applications.

A routine driver is a list of common task that can be executed on a remote server.

The built-in Laravel routine driver provides the following tasks:

• cache:clear
• clear:compiled
• composer:install
• config:cache
• config:clear
• down
• gulp
• gulp:production
• migrate
• optimize
• route:cache
• route:clear
• storage:link
• up
• view:clear

Extending Hermes

Custom Tasks

You can extend the standard Routine Driver by adding your custom tasks in your app service provider as following:

$this->app[ 'hermes.routine' ]->extend ( 'custom:task', function ( RoutineDriver $routine ) {
    $routine->command ( [
		'chmod -R 775 bootstrap/cache'
    ] );
} );

In the example below we extend the standard routine through the container binding $this->app[ 'hermes.routine' ] with a new task called 'custom:task'. In callback function with add a shell command to change the permission on the bootstrap/cache folder.

Custom Routines

If you need even more flexibility you can extend the Routine Manager by defining your own Routine Driver as following:

$this->app[ 'hermes' ]->extend ( 'custom-driver', function ( $app ) {
    return new CustomDriver();
} );

Note: the custom driver must implement the RoutineDriver contract or extend the built-in AbstractDriver.