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. The notable differences are using passenger 3 and system wide rvm.
At the time of writing, the latest versions of the software in use are:
- RVM: 1.0.21, system wide
- Ruby: 1.9.2-p0
- Passenger: 3.0.0
- Rails: 3.0.2
- Capistrano: 2.5.19
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 System Wide Install
rvm is installed system wide as this is now the best practice for deployments. 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 -L http://bit.ly/rvm-install-system-wide )
In order for a user to use the system wide rvm installation the following must be setup:
- User must belong to the rvm group - system wide installation requires the correct permissions
- User must use the rvm load script in profile files - the location of the load script is different to user specific installs
- User must not have
~/.rvm
- a user specific install overrides a system wide one
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 system wide 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
Simply edit .bashrc
and add the following line at the bottom:
[[ -s /usr/local/lib/rvm ]] && source /usr/local/lib/rvm
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 notes about requirements for installing the different rubies by running rvm notes
. The list of packages at the time of writing had dependency conflicts which can be circumvented by removing libreadline5-dev
.
To install the packages (requires sudo):
sudo apt-get install openssl curl git-core subversion autoconf \
build-essential bison zlib1g zlib1g-dev \
libssl-dev libxml2-dev libreadline5 libreadline-dev \
libreadline6-dev libsqlite3-0 libsqlite3-dev sqlite3
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-p0/gems/passenger-3.0.0/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-p0/gems/passenger-3.0.0
PassengerRuby /usr/local/rvm/wrappers/ruby-1.9.2-p0/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("~/.rvm/lib"))
require 'rvm/capistrano'
set :rvm_ruby_string, '1.9.2-p0'
set :rvm_type, :system
# 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
desc "Symlink shared resources on each release - not used"
task :symlink_shared, :roles => :app do
#run "ln -nfs #{shared_path}/config/database.yml #{release_path}/config/database.yml"
end
end
after 'deploy:update_code', 'deploy:symlink_shared'
Note: the above file supplies the rvm ruby version as 1.9.2-p0
. 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 and previous articles then 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
Testing
View your website in your browser and ensure it is loading.
Comments
blog comments powered by Disqus