library minion

nimbly/minion

Framework and language agnostic remote deployment automation tool

How it works

minion creates a new checkout/clone of your repo for each deployment. This allows clean installs and easy rollbacks to previous releases. The general idea is a single directory holds the releases and a symlink points to the current release., _(*1)

NOTE: In order for this to work with your webserver (Apache, Nginx, etc), you will need to update its configuration to point to the symlink as its webroot., _(*2)

During deployment, minion will apply your deployment strategy on each defined server. A deployment strategy is simply a list of tasks you would like minion to run., _(*3)

minion has several built-in tasks - however, you will need to create and implement your own tasks to take full advantage. Some examples: install composer, run migrations, flush caches, restart web service, restart web application, etc., _(*4)

Install

composer require nimbly/minion, _(*5)

Initialize

minion make:init, _(*6)

Configure

If you run the make:init command, minion will create a couple directories (Tasks and Commands) as well as generate a default configuration file (minion.yml)., _(*7)

The first several sections of the config file define global config options. Each environment defined may optionally override these global options., _(*8)

The global sections are:, _(*9)

• remote
• authentication
• code

remote

The remote section defines options on the remote server environment including where to deploy code., _(*10)

The options for the remote sections are as follows:, _(*11)

• path [string] The absolute path to the code on the server. I.e. the path to deploy code to., _(*12)

• releaseDir [string] The path to keep the releases (relative to path)., _(*13)

• symlink [string] Name of the symlink to create to point to current release., _(*14)

• keepReleases [integer] The number of releases to keep before pruning old releases., _(*15)

authentication

The authentication section defines how SSH can authenticate with your servers. You can either authenticate with a username and password or using a username, key and (optionally) a key pass phrase., _(*16)

NOTE: because minion uses PHPSECLIB as its core SSH library, you can only use RSA keys - DSA keys are not supported at this time., _(*17)

The options for the authentication sections are as follows:, _(*18)

• username [string] The SSH username to connect with., _(*19)

• password [string] optional The SSH password to use (if not using key based authentication)., _(*20)

• key [string] optional Path and file name of RSA key file., _(*21)

• passphrase [string] optional Pass phrase for key (if using key based authentication)., _(*22)

code

The code section defines how and where your code is stored., _(*23)

• scm [git, svn] What source code management tool you use., _(*24)

• repo [string] Repository URL/location, _(*25)

• branch [string] optional Repository branch (if any), _(*26)

• username [string] optional Repository username, _(*27)

• password [string] optional Repository password, _(*28)

environments

This section is where you define your server groups or environments. Each environment has a unique name and a list of servers. You must define a deployment strategy and provide an array of servers. A server must have a host property., _(*29)

• strategy [string] Comma separated list of tasks to run, in the order specified.
• servers [array] Array of servers to deploy to
• preDeploy [string] Comma separated list of tasks to run before the deploy happens. These tasks will be run on the local machine (i.e. not remotely).
• postDeploy [string] Comma separate list of tasks to run after the deploy happens. These tasks will be run on the local machine (i.e. not remotely).

For example:, _(*30)

environments:
    production:
        strategy: release, link, prune
        servers:
            - host: web-001.example.com
            - host: web-002.example.com
            - host: web-003.example.com

Within each environment, you may override some or all global options. For example, if your staging environment has a different set of SSH keys used to authenticate and uses the staging branch of your repo, you can define those changes within the staging environment., _(*31)

For example:, _(*32)

environments:
    staging:
        strategy: release, link, prune
        code:
            branch: staging
        authentication:
            username: deploy
            key: staging_id_rsa.pub
        servers:
            - host: staging-001.example.com
            - host: staging-002.example.com

A server may also override the environment strategy. This is useful if you have several servers and need to run a migration as it only needs to be run once., _(*33)

For example:, _(*34)

environments:
    staging:

        code:
            branch: staging

        authentication:
            username: deploy
            key: staging_id_rsa.pub

        strategy: release, link, prune

        servers:
            - host: staging-001.example.com
              strategy: release, link, migrate, prune
            - host: staging-002.example.com

Tasks

A task is one or more shell commands that are issued on the remote server. minion is pre-configured with four tasks., _(*35)

• release Creates a new release on the server.
• link Symlinks the newly created release to the current release directory (current by default).
• prune Prunes (deletes) old release directories.
• update Does a code update on the current release (git pull or svn up)

Extending

minion can be extended by creating new custom commands as well as custom tasks., _(*36)

Commands

To create a new command:, _(*37)

minion make:command <name>, _(*38)

For example:, _(*39)

minion make:command CacheFlushCommand, _(*40)

Custom commands can be found in the Commands directory where you run minion from., _(*41)

minion commands are powered by Symfony Console. Please refer to [http://symfony.com/doc/current/components/console.html] for documentation., _(*42)

Tasks

To create a new task:, _(*43)

minion make:task <name>, _(*44)

For example:, _(*45)

minion make:task Migrate, _(*46)

Custom tasks can be found in the Tasks directory where you run minion from., _(*47)