Negroku is an opinionated collection of recipes for capistrano.
The goal is to be able to deploy ruby on rails applications and static websites without the hassle of configuring and defining all the stuff involved in an application deployment.
All the server settings pre-defined in the configuration files generated by negroku are targeted to this server generic configuration guide. Although in most cases you can customize those settings.
Install negroku as a global gem.
$ gem install negroku
Add the negroku gem to your
Gemfile development group to lock the version your are going to use.
group :development do gem 'negroku', '1.1.4' end
You will need to add to your Gemfile these two gems:
group :assets do gem 'therubyracer', :platforms => :ruby end group :production do gem 'unicorn' end
$ bundle install
Note: Add the
therubyracer gem only if your are going to use the assets precompile of a rails project.
Create your app executing the following command, and just follow the on-screen questions.
$ negroku app create
Give your application a name
This will be used to create the app folder structure in the server and to name some files, for example, the log files.
Please choose your repository
You'll need to choose the git respository where your are going to store your project. Typically a GitHub repository, it can be any repository that the server has access to.
If you have already initializated your git repository for the project, you'll be offered to choose the remotes of the current repo.
You'll need to choose the server address where the project will be deployed and the hostname that will be used by nginx to host the application. Negroku will ask this for two stage servers (staging, production)
Note: Refer to the negroku config taks to add some default servers to the negroku configuration.
app createcommand will bootpstrapp your app (behind the scenes it will run the capistrano command
capify .and add some customizations)
Some files and folders will be added to your project, this is the same structure that capistrano expects when using multistage extensions
project_root |--- Capfile # Capistrano load file +--- config |--- deploy.rb # Global setting for all environments +--- deploy |--- production.rb # Specific settings for production server +--- staging.rb # Specific settings for staging server
Configure your specific settings in the files created above
Common settings for all stages
Here you can add all the settings that are common to all the stage severs.
#You may want to change the stages and the default stage set :stages, %w(production staging) set :default_stage, "staging"
Here you can add all the settings that are specific to the stage.
#You may want to change the repository branch for each stage. set :branch, "production" # Optional, defaults to master
Prepare the server for your application executing
$ cap deploy:setup
Commit and push the changes to the repository
Configure all your environmental variables for your project using the negroku env taks
Deploy you application for the first time executing
$ cap deploy:cold # for the default stage $ cap production deploy:cold # for the production stage
For all the next following deploys, you should execute
$ cap deploy # for the default stage $ cap production deploy # for the production stage
Negroku also provides a simple CLI that helps to initialize the deployment of your project and that wraps some tasks from its recipes collection.
To achieve this goal negroku provides a set of pre-configured capistrano recipes and deploy configuration files in order to streamline the process to deploy a new application.
cap nginx:reload # reload Nginx. cap nginx:restart # restart Nginx. cap nginx:setup # Setup nginx configuration for this applic... cap nginx:start # start Nginx. cap nginx:stop # stop Nginx. cap nginx:upload_ssl_certificates # Upload SSL certificates for this applicat...
cap unicorn:add_worker # Add a new worker cap unicorn:duplicate # Duplicate Unicorn cap unicorn:reload # Reload Unicorn cap unicorn:remove_worker # Remove amount of workers cap unicorn:restart # Restart Unicorn cap unicorn:setup # Setup unicorn configuration for this appl... cap unicorn:shutdown # Immediately shutdown Unicorn cap unicorn:start # Start Unicorn master process cap unicorn:stop # Stop Unicorn
cap log:app # Stream (tail) the application's productio... cap log:nginx_access # Stream (tail) the nginx access log. cap log:nginx_error # Stream (tail) the nginx error log. cap log:unicorn_error # Stream (tail) the unicorn error log.
cap rbenv:vars:add # Add rbenv vars cap rbenv:vars:show # Show current rbenv vars cap rbenv:vars:symlink # Symlink rbenv-vars file into the current ...
Customizing the recipes
Aside of predefining some ways of doing the deployments, negroku is very flexible. This flexibility is inherited from capistrano, so you can extend negroku with your recipes, overide existing ones, and modify every configuration you want.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request