Featured New Media In Tibetan Participatory Knowledge > Geluk > An Introduction To Historical Polities In Tibet > Setting Up Thl Rails Apps On Localhost

THL Toolbox > Offline THL > Running THL from Your Local Server > Rails Apps on Localhost

Setting Up THL Ruby on Rails Apps on Localhost

Contributor(s): Andres Montano, Steve Weinberger, Than Grove

Setting up Rails in a Windows Environment

Windows is a more difficult environment to work with ROR in, since most ROR developers use Macs or Linux. These are notes about things to keep in mind when installing THL RoR apps on Windows machines (assuming you have a 32-bit system):

  • Install external link: Ruby 1.8.7
  • Make sure you have Mysql installed. If you are using MYSQL 5.* or greater, then you will probably have to install a separate ruby MYSQL driver as outlined at this external link: Aptana Forums thread. These instructions can be summarized as:
    1. download older MySQL client library, for example one from external link: InstantRails here
    2. Copy that dll file to the Ruby\bin folder on your installation. Often this is at: C:\\ruby187\bin.
    3. Restart MySQL from you WAMP controller.
  • Create a database with the appropriate name for the app usually "thl_{app name}_development".
  • Download a database dump for the application and using the import function in PhPMyAdmin to import the dump into the database you just created.
  • Install necessary ruby gems as follows:
gem install rails -v 2.3.4 --no-ri --no-rdoc --platform=mswin32

gem install mysql --no-ri --no-rdoc --platform=mswin32

gem install hpricot --no-ri --no-rdoc --platform=mswin32

Setting up Rails in a Mac Environment

  1. If you haven't already, be sure to install external link: XCode
  2. Ruby 1.8.7 (and Rails) come with pre-installed in Mac OS 10.5+, but you may need to update your versions. See instructions here: external link: Installing Ruby on Rails on Mac
  3. You may already have MySQL installed on your Mac, but otherwise you can install it from a number of sources. As of this writing, you can get it here: external link: Download MySQL Community Server.
  4. Install the necessary gems from the command line. Note that you may need to prepend 'sudo' – sudo gem install… – based on your environment. Try it without it first and then add it if you get an error.
gem install ruby-debug
gem install rack-openid -v0.2.2
gem install hpricot

The requirements for the mysql gem are different, based in part on what operating system you're running. For systems 10.5 and below:

sudo env ARCHFLAGS="-arch i386" gem install mysql -- 
  --with-mysql-dir=/usr/local/mysql --with-mysql-lib=/usr/local/mysql/lib 
  --with-mysql-include=/usr/local/mysql/include

For 10.6:

sudo env ARCHFLAGS="-arch x86_64" gem install mysql -- 
  --with-mysql-dir=/usr/local/mysql --with-mysql-lib=/usr/local/mysql/lib 
  --with-mysql-include=/usr/local/mysql/include

If you discover errors later calling for specific gems that are not installed, it's possible that this documentation is behind the development of the app. Just run gem install for whatever gem it says is missing.

Getting the Ruby on Rails Code with GIT

THL Ruby on Rails projects are hosted on GIT hub at external link: external link: http://github.com/THL. To access the code, do the following:

Getting GIT Up and Running

  1. Download and install GIT from external link: external link: http://code.google.com/p/msysgit/downloads/list. Once installed you will have to reboot your computer to get the "git" command to work in a command window or to show the GIT context menu.
  2. Create a folder for "thl-rails" on your hard drive, where all the ROR files will be located
  3. Open the Git Bash for that location by right clicking on the folder and choosing "Git Bash" (the GIT command window).
  4. Log onto Git at external link: https://github.com/ If you need to be added to a project, you will need to speak with a THL administrator.
  5. Click on Need help with public keys link
  6. Or, go to external link: external link: http://help.github.com/msysgit-key-setup/
  7. Follow the instructions for generating a SSH public key
  8. Follow the instructions for adding a key to your GitHub

Downloading THL ROR App Code to Your Computer.

  1. Right click on the "thl-rails" folder created above and choose the GIT BASH (Git command shell option) or open the Start menu and enter "Git Bash" in the Search Programs box and then in the resulting window navigate to the "thl-rails" folder
  2. Type: "git clone git@github.com:thl/kmaps" for Knowledge maps etc. and the download will begin
  3. Type: "cd kmaps" to change into that directory
  4. Type: "git submodule init" which will initiate the submodules
  5. Type: "git submodule update" which updates the submodules

Updating Code

Once the code is initially downloaded it should be up to date but before one begins working on a local version it is always good to update it first using the following two commands:

  • Type: "git pull origin master" to update the main program code
  • Type: "git submodule update" to update the submodules

{Need to add link to information from old Google Wave document}

Customizing Your Local Version of Ruby on Rails App

To run an ROR app locally you will need the corresponding data. You need to talk to a THL administrator about acquiring the required data for the app. This will come in a gzipped or zipped file. You will need to unzip it and import it into your local database program. These instructions discuss MySQL but some ROR apps use PostGres. The name of the database will generally be "{name of app}_development", e.g. "kmaps_development", etc, and you will need a data dump for that database to import into a local version of it. The following list will outline the steps needed to install the data for the Kmaps app:

  • Using PHPMyAdmin for your localhost version of MySQL, enter "kmaps_development" in the "Create New Database" field and click the create button.
  • Then click on the "Import" tab
  • Use the "Browse" button to find the .gz or otherwise compressed file that contains the database data for that project. Make sure the "Utf-8" encoding is selected and then press the "Go" button in the lower right corner. This will import the data into the database. If PHPMyAdmin gives you an error, it may be that the size of the data file is too big for the import tool. You can either external link: change the maximum allowable size for php uploads or use the external link: mysql command line tool.
  • Find and open in a text editor the file "database.example" in the config folder of the app
  • For the "development" entry, change the "username" and "password" to match your settings for your local MySQL. Often this will simply be "root" and nothing
  • Save the file as "database.yml". The appropriate section of that file should look something like this:
development:
  adapter: mysql
  encoding: utf8
  reconnect: false
  database: kmaps_development
  pool: 5
  username: root
  password: 
  host: localhost

The database, username, and passwords fields should all match the corresponding info for your localhost database for that app and for general MySQL logon.

Then to run the app you open a command window by pressing the windows button and "R" and typing "cmd". Navigate to the directory as in 

>cd C:\thl-repos\thl-rails\kmaps\
>ruby script/server

Then the app will be running at: external link: http://localhost:3000/

Troubleshooting

  • The app may be calling for a gem you don't have. If so, take note of the gem name and install it with gem install <gem name> (or sudo gem install <gem name>).
  • If the app runs okay at first but then throws errors when you click links, the issue is probably that it is looking to other Rails apps that are not where it expects them to be. The best way to fix this is as follows:
  1. Stop the server with Ctrl+C (Command+C on Mac).
  2. Type: ruby script/console
  3. Type: Rails.cache.clear
  4. For the two apps you're not currently trying to use, open the <app name>_resource.rb file in app/vendor/plugins/<app name>_integration/app/models/. So, if you're using kmaps, you would find the places_integration.rb and media_management_resource.rb (mms) files.
  5. Make the following change in those files, and then restart the server with ruby script/server:

From:

elsif hostname.ends_with? 'local'
    self.site = 'http://localhost/master/kmaps/'

To:

elsif hostname.ends_with? 'local'
    self.site = 'http://dev.<app abbreviation>.thlib.org/'

The app abbreviations are "tmb" for kmaps, "mms" for the media management system, and "places" for the places dictionary.

Provided for unrestricted use by the external link: Tibetan and Himalayan Library