updated Feb 26 2008

This is a summary of how we build our servers and deploy our Rails apps from Windows with the the current pre-release version of deprec2 + capistrano2.

The summary of how to do the same thing on Linux can be found here.

We use Slicehost to host our Rails apps (highly recommended) and we use deprec + capistrano to build our slices and deploy our apps. Mike Bailey has been hard at work on deprec2, which builds on capistrano2 by Jamis Buck. Thank you to Mike and Jamis for making these great tools that make life easier.

My local machine is a Windows box with Ruby 1.8.6 and rubygems 1.0.1.

The target machine here was a Slicehost slice with Ubuntu Gutsy.

This will build the slice with Ruby 1.8.6 and latest rails (2.0.2 as of this writing) For serving up your app it installs mongrel+nginx (not apache - though it can easily be modified to use it)

We use another remote machine to hold our source repositories and access those via the svn+ssh protocol. That is reflected in these instructions.

Step 1 gets your local machine set up properly and is a one-time deal. You won’t have to repeat it for each new slice you build/deploy to.

Step 2 installs everything you’ll need on your slice and deploys your app

I wanted to get this posted sooner rather than later - it may be a bit terse - let me know if anything is confusing or inaccurate. I’ll TRY to keep these instruction updated as deprec2 moves into full release and other things change.

Step 1 - Set Up The Machine You Are Deploying From (Windows)

This will make sure your development machine is set up the right way so that building your slice goes smoothly. You won’t have to repeat this when you build/deploy to future slices.

1.1. Download the pre-release deprec2 gem

Deprec 2.0 isn’t quite released yet, but there is a pre-release gem available.
As of this writing it is at version 1.99-13. You can find it at deprec.org.

The specific URL is almost guaranteed to change, but as of now I grab the file from http://www.deprec.org/attachment/wiki/WikiStart/deprec-1.99.13.gem?format=raw

1.2. Install Deprec

gem install deprec-1.99.13.gem

Make sure you run this command from the same directory where you downloaded the deprec gem to.
This will also install the latest version of capistrano, should you not already have it.

1.3. Install fastthread

gem install fastthread

Some people are having trouble with this step. If it doesn’t work then grab the latest mswin32 gem file from http://rubyforge.org/frs/?group_id=1306 and install from the local file. That should work.

Fastthread is necessary if you are using Ruby 1.8.6 to avoid possible deadlocks when using capistrano (or so I hear)

1.4. Generate keys

If you don’t already have PuTTY, PuTTYGen, Pageant, etc. download the installer
from http://the.earth.li/~sgtatham/putty/latest/x86/putty-0.60-installer.exe”
and install them.

I also find WinSCP to be a helpful tool, though you won’t need it to get through these instructions.

PuTTY uses a different format for its keys than the Linux tools, So you’ll need to generate two versions of both the private and public key.

To generate your keys:

1. Run PuTTYGen
2. Set the key type to SSH-2RSA on the bottom
3. Set number of bits to 1024
4. Click Generate, move the mouse around as instructed
5. (optional) Enter a pass phrase and then enter it again to confirm
6. (optional) Enter a descriptive key comment
7. Create a directory to hold the keys - I use C:\keys
8. Click “save private key” -> save in key dir as mykey.ppk
9. Click “save public key” -> save in key dir as mykey.ppk.pub
10. Conversions menu, select “Export OpenSSH Key” -> save in key dir as mykey.openssh
11. Select all the text in the box that says “Public key for pasting into OpenSSH…”, right click, select Copy - then open a text editor (like Notepad) - paste that text in on one line - save the file in key dir as mykey.openssh.pub (make sure Notepad doesn’t stick a .txt extension on the end)

The .openssh ones will be used on the slice and other Linux machines. The .ppk ones are the Windows/PuTTY ones.

1.5. Setup a directory we can use for holding slice config files and create an environment variable that points there

This directory is not specific to any one rails project and once we set it up we can use it in the future to do some of the initial setup for other slices we may build.

mkdir config_slices
cd config_slices
mkdir config

Now add an environment variable to make this process work on Windows.

1. Control Panel -> System -> Advanced Tab -> Environment Variables
2. Click New (I made it under ‘User Variables’, but under ‘System Variables’ should work too)
3. Variable name: home
4. Variable value: /config_slices (use of forward slash is intentional + necessary)
5. click Ok, then Ok again

Now exit your command prompt, reopen it, and verify the variable is set to what you entered in step d by typing:

echo %home%

1.6. Create some files for Deprec/Capistrano

From within your config_slices directory:

depify .

This creates:
\config_slices\.caprc
\config_slices\Capfile
\config_slices\config\deploy.rb

1.7. Edit your .caprc

Open up \config_slices\.caprc with a text editor.

Uncomment and update this line to point it to your openssh private key

ssh_options[:keys] = %w(/keys/mykey.openssh)

and uncomment these lines:

ssh_options[:forward_agent] = ...
ssh_options[:paranoid] = ...

1.8. Generate some config files locally that will be pushed out to your slice in a future step

Make sure you are still in config_slices directory

cap deprec:ssh:config_gen

This step generates configuration files which will be used to configure the ssh client and server on the slice.
It also makes a directory to hold public keys for you and other users so deprec can find your keys and copy those out to the slice for you.

1.9. (optional) Make some changes to the sshd_config before you send it to the slice

This step changes a couple settings in the the file that will be used to configure the slice’s ssh server.
It will be more secure if you don’t make either of these changes, but there is a chance you might find them to be useful.

Edit config_slices\config\ssh\etc\ssh\sshd_config

If you still want to be able to ssh into your slice with a password (not only keys), change the line from

PasswordAuthentication no

to

PasswordAuthentication yes

If you still want to be able to ssh into your slice as root, change the line from

PermitRootLogin no

to

PermitRootLogin yes

1.10. Make some changes to the ssh_config before you send it to the slice

This step changes a couple settings in the the file that will be used to configure the slice’s ssh client.
This prevents the slice from getting a host key error when it uses ssh to check out your code from the svn repo.

Edit config_slices\config\ssh\etc\ssh\ssh_config

Change:

#StrictHostKeyChecking ask

to

StrictHostKeyChecking no

1.11. Copy your public key to a place where deprec can find it

copy c:\keys\mykey.openssh.pub C:\config_slices\config\ssh\authorized_keys\deploy_user

Note: this copies and renames the file from mykey.openssh.pub to deploy_user

You can put whatever you want for deploy_user - this will be the username we create on the slice later. I just use my last name.
deprec makes it easy to add/manage additional users on the slice in the future - no need to have a single, dedicated “deploy” user.

1.12. Copy your public key out to your svn machine

PUT SOMETHING HERE

Step 2 - Set up your slice and deploy your app

Now that our development machine is set up we can move on to dealing with our slice.

2.1. Create a new slice or rebuild one from SliceManager

Note your slice’s IP address and new root password.

2.2. Change the root password on the slice

From within config_slices directory:

cap deprec:users:passwd USER=root HOSTS=your.slice.ip.address

1. You will be prompted for which user to change the password for - default is root, which is what we want - so just hit enter
2. You will be prompted for root’s new password - type one in
3. You will be prompted for the slice’s current root password - enter the password slicehost emailed you

Your slice’s root password has been changed.

2.3. Create a new user on the slice to do your deployment with

From within config_slices directory:

cap deprec:users:add USER=root HOSTS=your.slice.ip.address

1. You will be prompted for a new username - enter whatever you used for deploy_user in step 1.11
2. You will be asked if this should be an admin account -> enter yes
3. It should tell you it has found the key you copied above (if not you named the key wrong or did not copy it to the correct place in 1.11) and ask if you want to copy it out to the slice - default is yes - so hit enter
4. You will be prompted for a new password for deploy_user -> enter one
5. You will be prompted for a password - enter your slice’s new root password from previous step

Your deploy_user has now been created on the slice and that users public key has been copied over.

2.4. (optional) Make sure your keys work and some stuff about Pageant

At this point your user has been created on the slice and you should be able to ssh into the
slice from your development machine.

If you want to make sure your keys are working properly:

1. Open up PuTTY, type deploy_user@my.slice.ip.address in the Host Name box
2. Expand Connection->SSH on the left hand tree and click Auth
3. Click Browse next to “Private Key file for authentication”
4. Choose C:\keys\mykey.ppk and click open in the file dialog
5. Now click the Open button on the bottom

It should ssh you in and you shouldn’t have to enter your password.
But if you used a passphrase when you made your key, you still would have had to enter it here.

Type exit to close that ssh connection

Now test out using Pageant to automatically provide your key and passphrase to PuTTY and save you some typing:

1. Start Pageant from the PuTTY Group in Start->All Programs
2. Pageant will run in the system tray (by the clock) - it is the little computer icon with the hat looking thing
3. Double click that Pageant icon
4. Select add key
5. Choose C:\keys\mykey.ppk
6. Enter the passphrase
7. Click Close
8. Now run PuTTY again
9. This time just type deploy_user@my.slice.ip.address in the Host Name box (nothing in Auth this time)
10. Click the Open button on the bottom

This time it should ssh you in to your slice with no password or passphrase. Pageant provides the key and passphrase and saves you some typing. This is handy during deployment.

Just remember Pageant has to be running. You can add a shortuct to your Startup so that Pageant runs and loads that key automatically when you boot up your Windows box.

From Windows Explorer:

1. Navigate to C:\Documents and Settings\USER\Start Menu\Programs\Startup
2. Right Click on the right hand pane; New->Shortcut
3. Browse to find Pageant; C:\Program Files\PuTTY\pageant.exe; Click Ok
4. Click Next
5. Enter a nickname like “Load My Keys”
6. Click Finish
7. Right-click on the newly created shorctut and click Properties
8. change Target to (with the quotes) “C:\Program Files\PuTTY\pageant.exe” c:\keys\mykey.ppk

Now Pageant will start up and load your key when you reboot/login. After you reboot/login you should be asked to enter the passphrase for the key. And then you should see Pageant in the system tray. If you double-click the Pageant icon your key should already be loaded.

2.5. Copy the ssh/sshd configs over to the slice

From within config_slices directory:

cap deprec:ssh:config USER=deploy_user HOSTS=my.slice.ip.address

This configures the ssh client and server on the slice according to the config files we generated/edited in Step 1.

2.6. Setup your deploy.rb

cd my_rails_project
depify .

Edit my_rails_project/config/deploy.rb:

If you do not keep database.yml under source control add this line at the top (after require ‘deprec’):

set :database_yml_in_scm, false

This will make sure that database.yml is symlinked from the shared/config dir (we’ll create that file later)
If you keep database.yml in source control you should not put this line in.

Now change the following lines to match your specifics:

set :user, "deploy_user"
set :application, "my_rails_project"
set :repository,  "svn+ssh://my_svn_useruser@my_svn/path_to/my_rails_project/trunk"  #or whatever
set :domain, "my.slice.ip.address" #or domain name if you have that setup
role :app, domain
role :web, domain
role :db,  domain, :primary => true

2.7. Install ruby/rails/mysql/mongrel/nginx and everything else you need on the slice

From within my_rails_project directory:

cap deprec:rails:install_rails_stack

And you thought that would be hard…
This step saves you a LOT of work (thank you Mike Bailey)
It takes a little while, ~10 min when I ran it.

2.8. Run the initial deploy to get things configured

From within my_rails_project directory:

cap deploy:setup
cap deploy

This sets up your application on the slice and does an initial check out from your svn.

2.9. Create database.yml on the slice if you don’t keep it in source control

Skip this step if database.yml is under source control.

Add the following to my_rails_project/config/deploy.rb inside the namespace:deploy block

db_params = {
  "adapter"=>"mysql",
  "database"=>"#{application}_#{rails_env}",
  "username"=>"root",
  "password"=>"",
  "host"=>"localhost",
  "socket"=>""
}

db_params.each do |param, default_val|
  set "db_#{param}".to_sym,
    lambda { Capistrano::CLI.ui.ask "Enter database #{param}" do |q| q.default=default_val end}
end

task :my_generate_database_yml, :roles => :app do
  database_configuration = "#{rails_env}:\n"
  db_params.each do |param, default_val|
    val=self.send("db_#{param}")
    database_configuration<<"  #{param}: #{val}\n"
  end
  run "mkdir -p #{deploy_to}/#{shared_dir}/config"
  put database_configuration, "#{deploy_to}/#{shared_dir}/config/database.yml"
end

Now run this task to create database.yml

cap deploy:my_generate_database_yml

Follow the prompts - this makes database.yml - the defaults are likely ok (just hit enter) at all of the prompts.

2.10. Create the database and apply migrations

Still from within my_rails_project directory:

cap deprec:db:create
cap deprec:db:migrate

This creates your database and applies your migrations.

2.11. Restart mongrel+nginx

Still from within my_rails_project directory:

cap deprec:mongrel:restart
cap deprec:nginx:restart

Now you should be able to point your browser at your slice and see your app running. Congrats!

If not, let me know and I’ll try to help…