Skip to content

dasuchin/grunt-ssh-deploy

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

grunt-ssh-deploy (Version: 0.4.1)

SSH Deployment for Grunt using ssh2.

Getting Started

This plugin requires Grunt ~0.4.4

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-ssh-deploy --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-ssh-deploy');

The tasks

Overview

In your project's Gruntfile, add a section named environments to the data object passed into grunt.initConfig().

grunt.initConfig({
  environments: {
    environment: {
      // Environment specific options here
    }
  },
});

This plugin will connect to your remote host, add a directory to releases/ in your remote_path, and create a symlink to the latest release.

The symlink by default is current, you can change this by setting current_symlink.

Usage

By setting an environment, you can deploy each specific one with grunt ssh_deploy:environment or rolling back with grunt ssh_rollback:environment.

Options

options.host

Type: String

Remote host to connect to.

options.username

Type: String

The username to connect as on the remote server.

options.password

Type: String

Password for the username on the remote server.

options.privateKey

Type: string

Path to your private key privateKey: require('fs').readFileSync('/path/to/private/key')

options.passphrase

Type: string

Passphrase of your private key if needed.

options.agent

Type: string

Set agent agent: process.env.SSH_AUTH_SOCK

options.port

Type: String Default value: '22'

Port to connect to on the remote server.

options.readyTimeout

Type: Number Default value: 20000

Default timeout (in milliseconds) to wait for the SSH handshake to complete.

options.deploy_path

Type: String

Full path on the remote server where files will be deployed.

options.local_path

Type: String

Path on your local for the files you want to be deployed to the remote server. No trailing slash needed.

options.current_symlink

Type: String Default value: 'current'

Path to directory to symlink with most recent release.

options.before_deploy, options.after_deploy

Type: String

Commands to run on the server before and after deploy directory is created and symlinked.

options.tag

Type: String|function Default value: the current date (as a timestamp)

The release tag, e.g. '1.2.3'. It can be a string or a function (in that case is called and the returned value will be used). It defaults to the current timestamp formatted as 'YYYYMMDDHHmmssSSS'.

WARN: release tag name matters. When used with parameter releases_to_keep the releases are reverse sorted alphabetically and older ones are removed. So be careful when you set your release tag name.

options.releases_to_keep

Type: Number

The number of builds (including the current build) to keep in the remote releases directory. Must be >= 1.

options.release_subdir

Type: String Default value: '/'

Name of the sub directory to store the release in. Useful when multiple projects get deployed to the same machine and the releases_to_keep option is being used.

options.release_root

Type: String Default value: 'releases'

Name of the root directory where all the releases are published. If a options.release_subdir is also provided then the latest will be appended after this path.

options.zip_deploy

Type: Boolean Default value: false

Compress the build before uploading.

options.max_buffer

Type: Number Default value: 200 * 1024

Largest amount of data allowed on stdout or stderr.

options.exclude

Type: Array Default value: []

List of folders or files to exclude from build.

Usage Examples

Custom Options

grunt.initConfig({
  // do not store credentials in the git repo, store them separately and read from a secret file
  secret: grunt.file.readJSON('secret.json'),
  environments: {
      options: {
        local_path: 'dist',
        current_symlink: 'current',
        deploy_path: '/full/path'
      },
      staging: {
          options: {
              host: '<%= secret.staging.host %>',
              username: '<%= secret.staging.username %>',
              password: '<%= secret.staging.password %>',
              port: '<%= secret.staging.port %>',
              debug: true,
              releases_to_keep: '3'
          }
      },
      production: {
          options: {
              host: '<%= secret.production.host %>',
              username: '<%= secret.production.username %>',
              password: '<%= secret.production.password %>',
              port: '<%= secret.production.port %>',
              releases_to_keep: '5',
              release_subdir: 'myapp'
          }
      }
  }
});

Before and After Hooks

grunt.initConfig({
  environments: {
    options: {
      local_path: '.',
    },
    production: {
      options: {
        host: '123.45.67.89',
        username: 'root',
        password: 'password',
        deploy_path: '/sites/great_project',
        before_deploy: 'cd /sites/great_project/releases/current && forever stopall',
        after_deploy: 'cd /sites/great_project/releases/current && npm install && forever start app.js'
      }
    }
  }
});

Release History

  • 2014/06/23 - v0.2.0 - Added rollback functionality.
  • 2014/06/19 - v0.1.7 - Fixed symlink method to cd into deploy_path before setting symlink.
  • 2014/05/04 - v0.1.5 - Changing symlink method to not use full path.
  • 2014/05/04 - v0.1.0 - Initial release.