This guide supersedes a number of
earlier guides,
providing the details to get up and running with a rack based
application from a basic ubuntu server VPS. It is a walkthrough of the
steps taken, and it is advisable to first read the installation
instructions provided by the software authors.
At the time of writing, the latest versions of the software in use are:
- RVM: 1.9.0
- Ruby: 1.9.2-p290
- Passenger: 3.0.9
- Rails: 3.1.1
- Capistrano: 2.9.0
You may need to alter the versions in the steps below as some
commands and paths contain explicit versions. The server used for
hosting in the guide is an
Ubuntu Lucid VPS, so tailor the steps to your platform accordingly. Also, substitute
domainname,
hostname and
appname as appropriate for your environment.
RVM Multi User Install
RVM can be installed for multiple users by installing as root. This
allows installations to be shared across different users, although
different users can use which ever version they wish.
Log in as root and install using the preferred script:
bash < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer)
In order for a user to use the multi user RVM installation the must
belong to the rvm group. Also check that they do not have a
~/.rvm directory as this takes precedence over the multi user install for that user.
Create Passenger User
It is a good idea to create a passenger user on the server to install
services as so that it is isolated from other users. You can also
deploy your applications using this user. The passenger user needs sudo
rights for installing packages using apt-get and running the passenger
install script, and needs to be a member of the rvm group to use the
multi user install.
sudo adduser passenger
sudo usermod -G passenger,www-data,sudo,rvm passenger
su - passenger
You can remove the sudo right after completing the installation using the following:
sudo usermod -G passenger,www-data,rvm passenger
Generate a key pair for ssh too. On your client machine, create a key and use a string pass phrase:
ssh-keygen -v -t rsa -f passenger@domainname -C passenger@domainname
This will create a private key called
passenger@domainname and a public key called
passenger@domainname.pub. Keep these somewhere safe.
You can register the public key into authorized_keys to allow key
based ssh authentication. Run the following on your client machine:
scp passenger@domainname.pub passenger@hostname:~/.ssh/authorized_keys
Depending on the client and your preference, you can either enter the
passphrase for you private key each time you connect, or run
ssh-agent and register the key using
ssh-add.
To register the private key into your ssh agent on your client machine
run the following and enter the passphrase when prompted:
ssh-add passenger@domainname
You should now be able to ssh to the server without being challenged for the password, e.g:
ssh passenger@hostname
Passenger RVM Configuration
Note: if you previously had RVM installed as a single user you need to remove the old source line for
$HOME/.rvm/scripts/rvm and move (or delete) the .rvm directory so that the system wide installation is picked up instead.
Log out and log in again as passenger to ensure the scripts work as
expected. You can test RVM is available correctly by running:
type rvm | head -n1
You should then see the following output:
rvm is a function
You can view the requirements for installing the different rubies by running
rvm requirements.
To install the packages (requires sudo):
sudo apt-get install build-essential openssl libreadline6 libreadline6-dev curl git-core zlib1g zlib1g-dev libssl-dev libyaml-dev libsqlite3-0 libsqlite3-dev sqlite3 libxml2-dev libxslt-dev autoconf libc6-dev ncurses-dev automake libtool bison subversion
To install ruby 1.9.2:
rvm install 1.9.2
rvm use --default 1.9.2
You can can now verify the ruby version and install some gems, e.g.:
ruby -v
gem install bundler rails
Passenger
Passenger is very easy to install. RVM provides some
instructions specifically for passenger.
Install the gem and run the installation script. It will tell you what dependencies you are missing and how to install them:
gem install passenger
passenger-install-apache2-module
Passenger provides some instructions on how to configure apache. I
like to treat passenger as a mod for apache, allowing it to be enabled
and disabled as required through the
a2enmod and
a2dismod commands respectively.
To enable passenger, create
/etc/apache2/mods-available/passenger.load with the following contents:
LoadModule passenger_module /usr/local/rvm/gems/ruby-1.9.2-p290/gems/passenger-3.0.9/ext/apache2/mod_passenger.so
and
/etc/apache2/mods-available/passenger.conf with the following contents:
PassengerRoot /usr/local/rvm/gems/ruby-1.9.2-p290/gems/passenger-3.0.9
PassengerRuby /usr/local/rvm/wrappers/ruby-1.9.2-p290/ruby
then enable the module and restart apache:
sudo a2enmod passenger
sudo /etc/init.d/apache2 restart
Apache
Each rack/rails application is made available through a virtual host
directive in the apache configuration. The recommended way to do this
is to create a file named after the site, e.g.
domainname in
/etc/apache2/sites-available and then enable and disable the site as required using the
a2ensite and
a2dissite commands respectively.
I prefer to put all web applications in
/var/www and have users be able to create applications if they are a member of
www-data:
sudo mkdir /var/www
sudo chown www-data:www-data /var/www
sudo chmod g+w /var/www
Hello World rack app
I find it useful to have a simple Hello World rack application to
verify the rvm and passenger installation. The application can be run
as a subdomain to allow testing and can be enabled and disabled as
desired.
Create the necessary directory structure for a rack application:
cd /var/www
mkdir hw.domainname
cd hw.domainname
mkdir public
mkdir tmp
Create
/var/www/hw.domainname/config.ru with the following contents:
app = proc do |env|
[200, { "Content-Type" => "text/html" }, ["hello, world"]]
end
run app
Create
/etc/apache2/sites-available/hw.domainname with the following contents:
<VirtualHost *:80>
ServerName hw.domainname
DocumentRoot /var/www/hw.domainname/public
<Directory /var/www/hw.domainname/public>
AllowOverride all
Options -MultiViews
</Directory>
</VirtualHost>
Enable the site, and then view it in your browser:
sudo a2ensite hw.domainname
sudo /etc/init.d/apache2 reload
This can then be disabled and reenabled if needed for debugging any issues at a later date:
sudo a2dissite hw.domainname
sudo /etc/init.d/apache2 reload
Rails app
You now need to create a virtual host for the rails app so that apache can handle the requests and pass off to passenger.
Create the necessary directory structure for a rails application (assuming its running as the domainname):
cd /var/www
mkdir domainname
Create
/etc/apache2/sites-available/domainname with the following contents:
<VirtualHost *:80>
ServerName domainname
DocumentRoot /var/www/domainname/current/public
<Directory /var/www/domainname/current/public>
AllowOverride all
Options -MultiViews
</Directory>
</VirtualHost>
Enable the site, although there is nothing there to view until we have deployed it:
sudo a2ensite domainname
sudo /etc/init.d/apache2 reload
Capistrano
The following steps should be performed on your client machine to capify an existing rails application and deploy it.
Configuration
Make sure you have capistrano installed:
gem install capistrano
Initialise the rails application:
cd ~/dev/appname
capify .
This will generate some files, along with a sample
config/deploy.rb. Replace the file contents with the following, using suitable values where applicable.
# RVM bootstrap
$:.unshift(File.expand_path('./lib', ENV['rvm_path']))
require 'rvm/capistrano'
set :rvm_ruby_string, '1.9.2-p290'
# bundler bootstrap
require 'bundler/capistrano'
# main details
set :application, "domainname"
role :web, "domainname"
role :app, "domainname"
role :db, "domainname", :primary => true
# server details
default_run_options[:pty] = true
ssh_options[:forward_agent] = true
set :deploy_to, "/var/www/domainname"
set :deploy_via, :remote_cache
set :user, "passenger"
set :use_sudo, false
# repo details
set :scm, :git
set :scm_username, "passenger"
set :repository, "git@gitserver:domainname.git"
set :branch, "master"
set :git_enable_submodules, 1
# tasks
namespace :deploy do
task :start, :roles => :app do
run "touch #{current_path}/tmp/restart.txt"
end
task :stop, :roles => :app do
# Do nothing.
end
desc "Restart Application"
task :restart, :roles => :app do
run "touch #{current_path}/tmp/restart.txt"
end
end
Note: the above file supplies the rvm ruby version as
1.9.2-p290. It is advisable to be specific about the version here as if this were
1.9.2 and a newer ruby version is available you may start to receive errors in the capistrano deployment.
Deployment
The first time you deploy to the server you should run the deployment setup task:
cap deploy:setup
Thereafter you can deploy using:
cap deploy
Or if you have database migrations to run then use:
cap deploy:migrations
You may get some strange errors or failures when deploying. If you
have followed the steps I have mentioned in this guide then hopefully
you shouldn’t have many problems. Common problems are:
- wrong permissions of
/var/www
- wrong permissions of passenger user
- not having rvm installed for passenger user
- not having the basic gems required to use capistrano on the server, simply install them as the passenger user
.
You really only need one or the other; pick whichever format you like.
.
This book serves as a great bridge to understanding Hypermedia APIs from the
RESTful world. Chapters one through four read like Richardson & Ruby; yet they
start slipping in the better hypermedia terminology. Chapter five really starts
to dig into how Hypermedia APIs work, and is a great introduction. Chapter six
covers scaling, chapter seven is an introduction to using ATOM for more than an
RSS replacement, nine is about security, and eleven is a great comparison of
how Hypermedia and WS-* APIs differ. All in all, a great intermediate book.
.
Don't let the title fool you, as Mike says in the introduction:
, while I haven't actually read it, seems quite terrible. Let me copy an
Amazon review: