=====Installing the Brightbox Gem=====

The Brightbox gem contains Capistrano 'recipes' that manage the deployment of a Rails application onto your Brightbox.

Capistrano operates on a management machine which remotely logs into your Brightbox and issues commands on it. You can read more about Capistrano on [[http://capify.org|the Capistrano website]]

Your management machine is often the machine where you have developed the application. However it doesn't need to be. All you need is a machine with RubyGems installed and which can access your Brightbox via the SSH protocol.

On an Ubuntu desktop simply install the rubygems package from a terminal window.
<code bash>
  sudo apt-get install ruby rubygems
</code>

== Download the gem ==

To install the Brightbox gem run the following from a terminal window
<code bash>
  sudo gem install brightbox -y
</code>

== Gather your application's details ==
Use the ''brightbox'' command to add the Brightbox recipes to your application. This works in the same way as the standard Capistrano ''capify'' but with additional options. You can see the options by running:
<code bash>
  brightbox -h
</code>

To add the recipes you will need the name of your Brightbox server, which you will find on the email you received when you signed up.

== Ready your application ==

Move into the directory where your Rails application is stored on the management station. (You may need to retrieve it from the version control repository you are using first). Then run the ''brightbox'' command on it to set up the recipes, e.g.
<code>
  brightbox -i example-001.vm.brightbox.net .
</code>
(Change the argument details as required for your own application and brightbox server).

This will create the file ''config/deploy.rb'' containing the details needed to deploy your application. Edit this file and change the settings as required.

== Update your server tools ==

The ''brightbox-server-tools'' gem needs to be installed on the server.  Brightboxes come pre-installed with the gem but you can make sure you have latest version with the following command:

<code>
  cap COMMAND="gem install brightbox-server-tools" SUDO=1 invoke
</code>

If you see a <code>sh: railsapp-maintenance: not found</code> message whilst deploying, you definitely need to update your ''brightbox-server-tools'' gem.


 
[[docs:gemv2:howto|Back to Index]]