Git Product home page Git Product logo

npm's Introduction

Capistrano: A deployment automation tool built on Ruby, Rake, and SSH.

Gem Version Build Status Code Climate CodersClan

Capistrano is a framework for building automated deployment scripts. Although Capistrano itself is written in Ruby, it can easily be used to deploy projects of any language or framework, be it Rails, Java, or PHP.

Once installed, Capistrano gives you a cap tool to perform your deployments from the comfort of your command line.

$ cd my-capistrano-enabled-project
$ cap production deploy

When you run cap, Capistrano dutifully connects to your server(s) via SSH and executes the steps necessary to deploy your project. You can define those steps yourself by writing Rake tasks, or by using pre-built task libraries provided by the Capistrano community.

Tasks are simple to make. Here's an example:

task :restart_sidekiq do
  on roles(:worker) do
    execute :service, "sidekiq restart"
  end
end
after "deploy:published", "restart_sidekiq"

Note: This documentation is for the current version of Capistrano (3.x). If you are looking for Capistrano 2.x documentation, you can find it in this archive.


Contents

Features

There are many ways to automate deployments, from simple rsync bash scripts to complex containerized toolchains. Capistrano sits somewhere in the middle: it automates what you already know how to do manually with SSH, but in a repeatable, scalable fashion. There is no magic here!

Here's what makes Capistrano great:

Strong conventions

Capistrano defines a standard deployment process that all Capistrano-enabled projects follow by default. You don't have to decide how to structure your scripts, where deployed files should be placed on the server, or how to perform common tasks: Capistrano has done this work for you.

Multiple stages

Define your deployment once, and then easily parameterize it for multiple stages (environments), e.g. qa, staging, and production. No copy-and-paste necessary: you only need to specify what is different for each stage, like IP addresses.

Parallel execution

Deploying to a fleet of app servers? Capistrano can run each deployment task concurrently across those servers and uses connection pooling for speed.

Server roles

Your application may need many different types of servers: a database server, an app server, two web servers, and a job queue work server, for example. Capistrano lets you tag each server with one or more roles, so you can control what tasks are executed where.

Community driven

Capistrano is easily extensible using the rubygems package manager. Deploying a Rails app? Wordpress? Laravel? Chances are, someone has already written Capistrano tasks for your framework of choice and has distributed it as a gem. Many Ruby projects also come with Capistrano tasks built-in.

It's just SSH

Everything in Capistrano comes down to running SSH commands on remote servers. On the one hand, that makes Capistrano simple. On the other hand, if you aren't comfortable SSH-ing into a Linux box and doing stuff on the command-line, then Capistrano is probably not for you.

Gotchas

While Capistrano ships with a strong set of conventions that are common for all types of deployments, it needs help understanding the specifics of your project, and there are some things Capistrano is not suited to do.

Project specifics

Out of the box, Capistrano can deploy your code to server(s), but it does not know how to execute your code. Does foreman need to be run? Does Apache need to be restarted? You'll need to tell Capistrano how to do this part by writing these deployment steps yourself, or by finding a gem in the Capistrano community that does it for you.

Key-based SSH

Capistrano depends on connecting to your server(s) with SSH using key-based (i.e. password-less) authentication. You'll need this working before you can use Capistrano.

Provisioning

Likewise, your server(s) will likely need supporting software installed before you can perform a deployment. Capistrano itself has no requirements other than SSH, but your application probably needs database software, a web server like Apache or Nginx, and a language runtime like Java, Ruby, or PHP. These server provisioning steps are not done by Capistrano.

sudo, etc.

Capistrano is designed to deploy using a single, non-privileged SSH user, using a non-interactive SSH session. If your deployment requires sudo, interactive prompts, authenticating as one user but running commands as another, you can probably accomplish this with Capistrano, but it may be difficult. Your automated deployments will be much smoother if you can avoid such requirements.

Shells

Capistrano 3 expects a POSIX shell like Bash or Sh. Shells like tcsh, csh, and such may work, but probably will not.

Quick start

Requirements

  • Ruby version 2.0 or higher on your local machine (MRI or Rubinius)
  • A project that uses source control (Git, Mercurial, and Subversion support is built-in)
  • The SCM binaries (e.g. git, hg) needed to check out your project must be installed on the server(s) you are deploying to
  • Bundler, along with a Gemfile for your project, are recommended

Install the Capistrano gem

Add Capistrano to your project's Gemfile using require: false:

group :development do
  gem "capistrano", "~> 3.17", require: false
end

Then run Bundler to ensure Capistrano is downloaded and installed:

$ bundle install

"Capify" your project

Make sure your project doesn't already have a "Capfile" or "capfile" present. Then run:

$ bundle exec cap install

This creates all the necessary configuration files and directory structure for a Capistrano-enabled project with two stages, staging and production:

├── Capfile
├── config
│   ├── deploy
│   │   ├── production.rb
│   │   └── staging.rb
│   └── deploy.rb
└── lib
    └── capistrano
            └── tasks

To customize the stages that are created, use:

$ bundle exec cap install STAGES=local,sandbox,qa,production

Note that the files that Capistrano creates are simply templates to get you started. Make sure to edit the deploy.rb and stage files so that they contain values appropriate for your project and your target servers.

Command-line usage

# list all available tasks
$ bundle exec cap -T

# deploy to the staging environment
$ bundle exec cap staging deploy

# deploy to the production environment
$ bundle exec cap production deploy

# simulate deploying to the production environment
# does not actually do anything
$ bundle exec cap production deploy --dry-run

# list task dependencies
$ bundle exec cap production deploy --prereqs

# trace through task invocations
$ bundle exec cap production deploy --trace

# lists all config variable before deployment tasks
$ bundle exec cap production deploy --print-config-variables

Finding help and documentation

Capistrano is a large project encompassing multiple GitHub repositories and a community of plugins, and it can be overwhelming when you are just getting started. Here are resources that can help:

Related GitHub repositories:

  • capistrano/sshkit provides the SSH behavior that underlies Capistrano (when you use execute in a Capistrano task, you are using SSHKit)
  • capistrano/rails is a very popular gem that adds Ruby on Rails deployment tasks
  • mattbrictson/airbrussh provides Capistrano's default log formatting

GitHub issues are for bug reports and feature requests. Please refer to the CONTRIBUTING document for guidelines on submitting GitHub issues.

If you think you may have discovered a security vulnerability in Capistrano, do not open a GitHub issue. Instead, please send a report to [email protected].

How to contribute

Contributions to Capistrano, in the form of code, documentation or idea, are gladly accepted. Read the DEVELOPMENT document to learn how to hack on Capistrano's code, run the tests, and contribute your first pull request.

License

MIT License (MIT)

Copyright (c) 2012-2020 Tom Clements, Lee Hambley

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

npm's People

Contributors

allaire avatar blackjid avatar hannesvdvreken avatar inbeom avatar koenpunt avatar pjkelly avatar sorah avatar swalkinshaw avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

npm's Issues

capistrano/npm + yarn - npm = capistrano/yarn

Hello, I am not sure if this is the best place, but I wanted to start a discussion about how to create a new official Capistrano package.

Recently the Yarn JavaScript package manager was released. It is similar to NPM, which Capistrano has support for in capistrano/npm and which we have used at my place of work. I (and others) forked this repo to add Yarn support, but it might make sense to reduce effort duplication and to have a canonical gem/repo for installation.

What is the best way to create an official Capistrano gem / repo? I tried quickly looking at http://capistranorb.com/ and on the Github organization page for capistrano, but didn't see advice there (may have missed it though.)

Thanks for your help!

Empty node_modules dir

Added the configs according to README.

Added set :linked_dirs, %w{node_modules} to deploy file.

Addes set :npm_target_path, -> { release_path.join('node_modules') } to deploy file.

The deploy applies npm install but the folder end up empty.

My package.json:

{
  "private": true,
  "scripts": {},
  "devDependencies": {},
  "dependencies": {
    "express": "^4.16.2",
    "redis": "^2.8.0",
    "socket.io": "^2.0.4"
  }
}

SSHKit::Runner::ExecuteError: Exception while executing: npm exit status: 254

Hi,

I have been getting intermittent npm install errors during my capistrano deploy process. I'm getting back npm error code 254, which is a bit cryptic as I can't find much info about it online. This is the capistrano failure error when deploying with --trace:

DEBUG [e9c1e739] Command: cd /apps/appName/releases/20161005212751 && /usr/bin/env npm install --production --silent --no-progress
cap aborted!
SSHKit::Runner::ExecuteError: Exception while executing as [email protected]: npm exit status: 254
npm stdout: Nothing written
npm stderr: Nothing written
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/runners/parallel.rb:15:in `rescue in block (2 levels) in execute'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/runners/parallel.rb:11:in `block (2 levels) in execute'
SSHKit::Command::Failed: npm exit status: 254
npm stdout: Nothing written
npm stderr: Nothing written
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/command.rb:100:in `exit_status='
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/backends/netssh.rb:127:in `execute_command'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/backends/abstract.rb:137:in `block in create_command_and_execute'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/backends/abstract.rb:137:in `tap'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/backends/abstract.rb:137:in `create_command_and_execute'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/backends/abstract.rb:69:in `execute'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/capistrano-npm-1.0.2/lib/capistrano/tasks/npm.rake:18:in `block (5 levels) in <top (required)>'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/backends/abstract.rb:88:in `with'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/capistrano-npm-1.0.2/lib/capistrano/tasks/npm.rake:17:in `block (4 levels) in <top (required)>'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/backends/abstract.rb:80:in `within'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/capistrano-npm-1.0.2/lib/capistrano/tasks/npm.rake:16:in `block (3 levels) in <top (required)>'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/backends/abstract.rb:29:in `instance_exec'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/backends/abstract.rb:29:in `run'
/Users/jcursi/.rvm/gems/ruby-2.2.2/gems/sshkit-1.9.0/lib/sshkit/runners/parallel.rb:12:in `block (2 levels) in execute'
Tasks: TOP => deploy:updated => npm:install
The deploy has failed with an error: Exception while executing as [email protected]: npm exit status: 254
npm stdout: Nothing written
npm stderr: Nothing written

Any ideas on why this is occurring? Thanks!

Put node_modules in linked_dirs?

As the title suggests, what do you think about it?
The main advantage would be to speed up deploys, and as I see bundler plugin does a similar thing (although Bundler supports saving to a different path natively, npm will always install to ./node_modules).

I don't know if this is possible from the npm plugin itself (I have little Ruby and capistrano internals knowledge), but we can at least give a hint to users in the read me.

At the moment I simply added

set :linked_dirs, %w{node_modules}

in deploy.rb and it works perfectly.

Thanks.

Capistrano 3 `sudo` npm install

this is more of an observation/request for clarification than an issue:

based on #1, try_sudo is being invoked for the npm install ... however, it seems that Capistrano 3 has deprecated try_sudo (and the use_sudo configuration setting). i guess the current stance for Capistrano 3 is to configure proper user groups & privileges instead? i assume try_sudo would stay in the npm cap task for Capistrano 2 compatibility?

Capistrano/npm is not working

I am trying to deploy Rails app , that has some assets which should be installed via bower.
But when I add the "capistrano/npm' and 'capistrano/bower' , capistrano can not find the npm binary so can not install bower totally.
Here is error message:

DEBUG [432a0042] Command: cd /home/ubuntu/apps/datraks/releases/20170630155025 && /usr/bin/env npm install --production --silent --no-progress

DEBUG [432a0042] /usr/bin/env: npm: No such file or directory

I already have installed npm in server... Is there any solution to fix this?

Does flow order need changing?

I've found for my workflow that the default attachment of npm:install is too early.
It runs before my deploy repo has been cloned, so it doesn't have the updated package.json, thus doesn't install the correct node modules for the current version.

I've kinda hack solved it, by removing the task from 'before :updated' and reattaching after.

Rake::Task['deploy:updated'].prerequisites.delete('npm:install') # don't run npm before repo updated
after :updated, 'npm:install' # has to run after git clone to get updated pacjage.json

I'm wondering if instead it's worth doing a fork, changing the default, then pull request?

Support for capistrano v3

Hi, are you planning to support capistrano v3?

I can make a pull request adding that support, but

How can we support both capistrano versions??

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.