Grunt Deployment over SSH with Git

Grunt Logo

Grunt.js is a task runner that comes with various plugins for compiling, building, formatting, etc. within your project. I covered some of the basics of using this tool in my article about using Grunt Watch and LiveReload for real-time compilation.

I recently setup a simple deployment process using Grunt, so I thought I’d share the details. I found a couple deployment-related Grunt plugins out there, but they didn’t really suit my needs. Instead, I opted to simply use the grunt-ssh plugin to connect to my server and run the necessary commands to update, build and restart my application. Let’s take a look at a simplified Gruntfile.coffee.

module.exports = (grunt) ->

  grunt.initConfig

    sshconfig:
      someserver:
        host: 'someserver.com'
        username: 'someuser'
        agent: process.env.SSH_AUTH_SOCK

    sshexec:
      deploy:
        command: [
          'cd /home/someuser/app'
          'git pull origin master'
          'npm install'
          'forever stop server.js'
          'forever start server.js'
          'forever list'
        ].join(' && ')
        options:
          config: 'someserver'

  grunt.registerTask 'deploy', [
    'sshexec:deploy'
  ]

  grunt.loadNpmTasks('grunt-ssh')

When the task above is executed, by running grunt deploy, a number of things will happen. Grunt will SSH into someserver.com, with the user someuser. It’ll then move into the /home/someuser/app directory, pull down the latest master from the git repo, run an npm install (which, in my case, also triggers a build task), then restart the application using the forever package.

Most of the commands (and definitely the host/user names) will need to be customized on your end to suite your needs. For instance, if this isn’t a Node.js project, you may not be using npm install or forever. You can replace those commands with the proper commands to build and restart your application. This example also assumes that you already have your Git repo setup in /home/someuser/app. You may have it somewhere else, or you may not be using Git at all, and instead need to pull down files using some other process.

The entire array specified under command can be updated to suite your needs. Because I’m combining the commands using &&, if any one of them fails, the deployment process will stop.

Notes on Authentication

The example above makes a couple assumptions about authentication which may not apply in your case, so I want to offer some alternatives.

SSH Login

In the code above you’ll see a line like this:

agent: process.env.SSH_AUTH_SOCK

This is telling the SSH process to login into the server using my active set of private keys. For this to work, I must have the server configured to accept my private key. In short, this means I need to have mykey_rsa in the ~/.ssh directory of my local machine, and the matching mykey_rsa.pub loaded into ~/.ssh/authorized_keys on the server. If you’re unfamiliar with this setup, or can’t make it work, you can change the agent line above to use a password instead, like this:

password: 'PASSWORD-GOES-HERE'

Git Access

A Git service, such as GitHub, will often require a private key to access your repository. This key should be passed automatically if you use the “agent” authentication method above. However, if things aren’t configured properly, you may get a permission error when the deployment process tries to access your remote Git repository. I ran into this on a CentOS 6.5 server. I solved it by creating a private key to access Git on the server, then wrapping the git pull origin master with some other commands to activate the key temporarily:

    sshexec:
      deploy:
        command: [
          'cd /home/someuser/app'
          'eval `ssh-agent`'
          'ssh-add ~/.ssh/github_rsa'
          'git pull origin master'
          'ssh-agent -k'
          ...

Conclusion

While perhaps not the most ideal candidate for deployment, Grunt can accomplish quite a bit. The example above is very simple, but the solution I’m currently using extends this code to include deployments to multiple servers, uploads to S3, and more. If you’re shopping around for a simple way to deploy your application, give the code above a shot.

  • Pingback: Grunt.js Deployment with Git - Justin Klemm | J...

  • CodeLearner

    Hey, thanks for the writeup! I’ve got a question: how do you handle failed deployments in production? For example, if a git pull doesn’t work, or if running a database migration breaks mid-way.

    Thanks.

    • http://justinklemm.com/ Justin Klemm

      Hey, that’s an excellent question.

      The code above doesn’t have much failure logic built in. However, one benefit of using “.join(‘ && ‘)” is that the commands will be executed in order and the sequence will halt if one of them fails. So for example, if the “git pull” fails, the sequence will stop. It will *not* continue on to the “npm install” command. That gives you some flexibility to order your commands in a way that prevents issues if a failure happens.

      Of course that’s very remedial failure support. If you need something more robust, you’ll need to do some coding. You may want to introduce “backup” and “rollback” commands of some type. You may also consider options outside of Grunt. Grunt isn’t really an ideal deployment system, but it’s flexibility let’s you do some simple deployments, like the example above.

      Hope that’s helpful!

  • http://www.58bits.com Anthony Bouch

    Nice write-up and I’ll take this approach for smaller deployments. For larger projects it would be great if there was an npm module similar to the ruby capistrano gem.

    • http://justinklemm.com/ Justin Klemm

      Thanks, Anthony. Yea, definitely agree. I’ve been looking for a node-centric equivalent to capistrano, but haven’t found anything yet. Let me know if come across something.

  • ericrowan

    This is a really helpful article. I’ve been able to work through a few snags but can’t get past one problem:

    > This key should be passed automatically if you use the “agent” authentication method above. However, if things aren’t configured properly, you may get a permission error when the deployment process tries to access your remote Git repository.

    I can’t seem to get my public key to be recognized and running into permissions issues on the server while trying to connect to GitHub. I’d rather not have to create another ssh key on the server and feel like this can be fixed, but I don’t know what else to try. Anyone have any suggestions?

    • http://justinklemm.com/ Justin Klemm

      Hey Eric, yea, unfortunately this is a common problem. The grunt-ssh package doesn’t have an option for forwarding the key when it connects. I worked briefly with a guy on Twitter to send a pull request that adds the option (https://github.com/andrewrjones/grunt-ssh/pull/72), but it hasn’t been merged yet… I’ll try to ping the package author again today and see if we can get it done.

      • ericrowan

        Thanks for getting back to me man. Grunt-ssh is working flawlessly for me other than the issue I noted above, and honesty I think the problem is on my end. Despite my best efforts, I wasn’t able to resolve my “access denied” when attempting to connect to GitHub on my Digital Ocean droplet. I eventually just did what I should’ve done in the first place and created a private key on the remote server.

        • http://justinklemm.com/ Justin Klemm

          Yea, that’s how I’ve gotten around it too. If we can get the grunt-ssh author to merge that pull request, we’ll be able to pass the authentication over the connection… but until that happens, I think placing a key on the server is the best workaround.