Knowledgebase
How can I deploy a Rails application onto my account?
Posted by Hazel G. on 15 October 2011 11:37 AM

Introduction

This guide will provide step by step instructions on deploying your Rails application onto our web hosting platform. In order to reach for developers demands, we have integrated our platform to be engineered around an existing powerful deployment tool which is Capistrano. Capistrano is a developer tool for deploying web applications. It is typically installed on a workstation, and used to deploy code from your source code management (SCM) to one, or more servers. Also, because we selected an open platform which is extremely common, you will find solutions for any problems you run to online.

Prerequisites

In order to deploy code on our platform, you must have a select few utilities available. However, the majority of those utilities should be installed if you have done any Ruby or Rails development.

Required Gems
capistrano — This can be installed by running gem install capistrano
capistrano-vexxhost — This can be installed by running gem install capistrano-vexxhost
Other requirements
SSH access — You can request SSH access by contacting us and it will be enabled on your account
Source code management — You may (but must) use any source code management system. A simple one that is very easy to get started with is Git. You can host your code online for free with GitHub.

Architecture

If you have used Capistrano before, you may want to know how everything works exactly and not require the rest of the document. You must make sure that you install the capistrano-vexxhost gem and requiring the extension to install the additional commands.

When calling the cap deploy:setup command, it will set up the remote folders required for Capistrano in a folder named with the application name inside the apps folder in the root of your account.

Afterwards, you can continue to deploy with Capistrano just like if you were deploying to any normal server. Once deployed, you'll notice that the server will be running on a separate port, even if it's running, you will not be able to access it.

You will need to mount it onto your website, please read the "Mounting Application" section for instructions on mounting the application onto your website. The start/stop/restart commands are all setup to manage your Rails instance directly.

Getting Started

You must first have a copy of the latest source that you wish to deploy to your server, you have two options in this case. You may either choose to deploy the local source code on your computer or from a source code management system that is hosted online.

In the first case, Capistrano will upload the files from your machine to our servers directly. However, in the second case, our server will download the source code for you from the remote server. You must select how you will be doing the deployment so you can take care of this.

You must also make sure that you create the correct MySQL databases and correctly configure the database.yml file to point towards the database. Please note that even that your database will be hosted remotely, you must leave the host option to localhost in the configuration file. This is because when the application will run on the server, it will be looking for localhost.

Preparing application for deployment

In order to prepare your rails application for deployment, you must run the following command inside the folder of your application:

capify .

This will generate numerous files, the file that you will need will be located in the config directory, named deploy.rb. We recommend that you replace what was generated by the following template:

require 'capistrano'
require 'capistrano-vexxhost'

# Account Settings
set :user, "acct_username"
set :password, "acct_password"
set :domain, "acct.domain.com"
set :mount_path, "/"
set :application, "app_name"

The user and password should contain your cPanel account information. The domain name should contain the domain name that you want the host the application under (you must make sure the domain name exists under your account as the main domain name or an add-on domain name). The mount path is the path that the application will be loaded on your site, you can select to have it loaded in a subfolder if you wish. The application is a unique name for your application that will be identify your application to the server.

We also have a few extra recommendations that we suggest for our customers to do in order to make things easier, which include adding the following under the require line.

require 'bundler/capistrano'

This will run a bundle install remotely after deployment and will make sure that all the Gems that your application requires are all activated and there. This makes dealing with problems a lot easier and removes the possibility that you have missing or invalid dependancies. We recommend you put it in unless you have a reason not to.

For the remaining part of the configuration, you will have to select from the two options of either deploying from local source code (recommended if you are not sure / first deployment).

Local source code

set :repository, "/Users/dev/code/deploy_app"
set :local_repository, "/Users/dev/code/deploy_app"
set :scm, :git
set :deploy_via, :copy

You can read more information about those options in the Capistrano manual. However, for a small summary, the repository and local repository must be the same when we are copying data remotely. The SCM option gives the choice of what source code management is being used, you see Git here however you can use subversion or any other supported Capistrano deployment method. The last option tells Capistrano to deploy by copying the files locally and uploading them to the remote server.

Remote source code

set :scm, :git
set :repository, "git@github.com:user/repo.git"

This has far less options for configuration, however, you must know that our server will be downloading the source code for you. This means that you must make sure the server has access to it by installing the appropriate private keys on the server. You can also choose to forward your SSH keys to our servers for the duration of the session which is the recommended setup. You can read more about this in the Capistrano manual.

Preparing server for deployment

While you're in your main application folder and after you configured everything, you can run the following command:

cap deploy:setup

This command should be ran once for the first time that you deploy you application, you should not have to run this again unless you're adding a new application. Also, please note that if you run it again, you may run into errors so we recommend that it is only run once.

Deploying Application

This is the actual part that will occur often, the first time you will deploy and setup your account, we recommend that you run the following command:

cap deploy:cold

The cold part means that the server is not running at all and it's a deployment from zero. This is because it's the first time we do this, any further deployments, you should run this command instead:

cap deploy

As the second command assumes that everything is already running and we only need a reload at the end. In the event that the normal deployment does not work, you can try forcing a cap deploy:cold again just in case.

Once you run that command, you will see a lot of text go by however Capistrano will be in the process of uploading all your code, setting it up, running migrations, updating the bundles and starting the Rails application remotely, this is all handled for you. You can read more about how Capistrano does this in the user manual.

Mounting Application

Once your application is running on the remote server, you will need to mount it on your website. If the application is running, there is no way for anyone to access your application. By mounting it, you will expose it to the internet, first, you must make sure that you have the mount_path settings configured properly. That will be the path where your application will be hosted. Once you're ready to release it, you can run this command:

cap deploy:mount

You should get a confirmation that the application has been mounted, if you go to the URL for your website, you'll find that it will be running with no problems at all. The path for the site should be a mix of both the mount_path and domain. With the configuration that was specified in the beginning of the document, the path for the application would be: http://acct.domain.com/

Troubleshooting

Usually, any problems that you'll encounter will be within Capistrano, so you can check online for the error and you should find results on what the issue is exactly.

If you run into an issue that does not seem to have any documentation about online, it may be an issue within our system, so please contact us with the exact error message and we'll take care of this for you.

(12 vote(s))
Helpful
Not helpful

Comments (0)
Post a new comment
 
 
Full Name:
Email:
Comments:
CAPTCHA Verification 
 
Please enter the text you see in the image into the textbox below (we use this to prevent automated submissions).