Webappbuilders.com - Web Application Architecture: Principles, Protocols, and Practices

Instructions for Downloading and Installing the Administrative Interface Application (Unix/Linux/Mac OS X)

Here are the instructions for installing the sample Rails application, the VRLS Administrative Interface, described in Web Application Architecture: Principles, Protocols, and Practices. You will need the book to get the full tutorial benefit of the application.

These instructions assume that you have already downloaded and installed the MySQL database system and set it up for use with the book's main application, Virtual Reality Listing Services. If you have not, this page provides useful information.

Instructions for installing this application in a Windows environment can be found here.

NOTE: Because Rails seems to change significantly from release to release, making it difficult to pin down a stable set of instructions for installing it, we encourage you to visit the Rails wiki for up-to-date instructions and other related information. In particular, the pages devoted to Installing Ruby on Rails on Debian/Ubuntu, Red Hat/Mandriva, and Mac OS X are all useful resources.

First, download and install Ruby.

For Linux environments, visit the Rails wiki link above that's appropriate for your environment's flavor of Linux. Follow the instructions under the heading Install Ruby from repository.

For Mac OS X instructions, visit the Mac OS X installation page on the Rails wiki. (Apple's Developer Connection has its own pages devoted to Developing Rails Applications on Mac OS X Leopard.)
Make sure all the Ruby components are up to date, then install Rails using the following commands from the command line. (On a Mac, you get a command line prompt by opening the application called Terminal, which is found in the Applications/Utilities folder.)

$ sudo gem update --system
Updating RubyGems...
Bulk updating Gem source index for: http://gems.rubyforge.org
Attempting remote update of rubygems-update
Successfully installed rubygems-update-1.3.3
1 gem installed
Updating version of RubyGems to 1.3.3
Installing RubyGems 1.3.3
Installing RubyGems
Installing gem executable
Removing old source_cache files
    ...
RubyGems system software updated
$ sudo gem install rails --include-dependencies --no-ri --no-rdoc
INFO:  `gem install -y` is now default and will be removed
INFO:  use --ignore-dependencies to install only the gems you list
    Successfully installed rake-0.8.7
    Successfully installed activesupport-2.3.2
    Successfully installed activerecord-2.3.2
    Successfully installed actionpack-2.3.2
    Successfully installed actionmailer-2.3.2
    Successfully installed activeresource-2.3.2
    Successfully installed rails-2.3.2
7 gems installed

Rails is no longer distributed with the MySQL database adapter. The process of downloading and installing the MySQL adapter differs depending on your operating system environment. For environment specific details, go to the database support page in the Ruby on Rails wiki and follow the instructions there. (For Mac OS X, note that you may need to install the native MySQL driver.)
Once you have installed and updated Ruby, Rails, and the MySQL adapter, you are ready to begin building the application. Create a directory that will contain your Rails applications and "cd" into that directory. Then run the rails command to build the application project, and "cd" into the project directory.

$ mkdir ~/rails_apps
$ cd ~/rails_apps
$ rails -d mysql vrlsadmin
      create  
      create  app/controllers
      create  app/helpers
      create  app/models
      create  app/views/layouts
      create  config/environments
          ...
$ cd vrlsadmin

Edit the database configuration file (config/database.yml) - make sure the "mysql" adapter is enabled and provide appropriate credentials.

development:
  adapter: mysql
  encoding: utf8
  reconnect: false
  database: vrlsadmin_development
  pool: 5
  username: root
  password: your-mysql-root-password
  host: localhost

test:
  adapter: mysql
  encoding: utf8
  reconnect: false
  database: vrlsadmin_test
  pool: 5
  username: root
  password: your-mysql-root-password
  host: localhost

production:
  adapter: mysql
  encoding: utf8
  reconnect: false
  database: vrlsadmin
  pool: 5
  username: root
  password: your-mysql-root-password
  host: localhost

Set up your MySQL database server with a vrlsadmin_development database. Create and populate the tables by running scripts provided with the original VRLS application. (Alternatively, you can use these links to download the dbschema.sql and populate.sql files.)

$ mysql -u root -p
Enter password: ********
Welcome to the MySQL monitor.
Commands end with ; or \g.
Your MySQL connection id is 13
Server version: 5.0.37
MySQL Community Server (GPL)
Type 'help;' or '\h' for help.
Type '\c' to clear the buffer.
mysql> create database vrlsadmin_development;
Query OK, 1 row affected (0.00 sec)
mysql> use vrlsadmin_development;
Database changed
mysql> source dbschema.sql
    ...
mysql> source populate.sql
    ...

Run the "script/generate scaffold" commands to build model/view/controller scaffolding for objects.

NOTE TO WINDOWS USERS:
Entering "script/generate ..." at the command prompt will not work in a Windows environment, due to limitations in the way Windows operates.

Instead, type "ruby script\generate ..." (note the use of the backslash). Read this document for more specific instructions on installing this application in a Windows environment.

$ script/generate scaffold Listing listing_id:integer \
    listing_title:string \
    listing_desc:text \
    listing_type_code:integer \
    listing_region:integer \
    listing_offer_type_code:integer \
    listing_num_bedrooms:integer \
    listing_num_bathrooms:integer \
    listing_monthly_payment:integer \
    listing_purchase_price:integer \
    referring_partner_id:integer \
    listing_status_code:integer \
    listing_status_eff_date:date \
    date_entered:date \
    date_last_modified:date
        ...

$ script/generate scaffold Customer \
    cust_id:integer \
    cust_login:string \
    cust_password_hash:string \
    cust_first_name:string \
    cust_middle_name:string \
    cust_last_name:string \
    cust_address1:string \
    cust_address2:string \
    cust_city:string \
    cust_state_province_code:string \
    cust_postal_code:string \
    cust_country_code:string \
    cust_email_address:string \
    cust_phone:string \
    cust_level:integer \
    referring_partner_id:integer \
    cust_last_visited:date \
    date_entered:date \
    date_last_modified:date
       ...

$ script/generate scaffold Partner \
    partner_id:integer \
    partner_name:string \
    partner_desc:string \
    partner_contact_name:string \
    partner_address1:string \
    partner_address2:string \
    partner_state_province:string \
    partner_postal_code:string \
    partner_country_code:string \
    partner_contact_email:string \
    partner_contact_phone:string \
    partner_code:string \
    partner_prefix:string
       ...

$ script/generate scaffold ListingImage \
    listing_id:integer \
    listing_image_name:string \
    listing_image_desc:string \
    listing_image_url:string \
    listing_thumb_url:string \
    is_primary_image:boolean
       ...

Run "script/generate model" commands to build model/view/controller scaffolding for auxiliary objects.

$ script/generate model ListingType
       ...

$ script/generate model ListingOfferType
       ...

$ script/generate model ListingStatus
       ...

Edit model definition files (app/models/*.rb) to point to correct table names and primary key columns.

app/models/listing.rb

class Listing < ActiveRecord::Base
    set_table_name "vrls_listings"
    set_primary_key "listing_id"
end

app/models/customer.rb

class Customer < ActiveRecord::Base
    set_table_name "vrls_customer_profile_data"
    set_primary_key "cust_id"
    belongs_to :partner, :foreign_key => "referring_partner_id"
end

app/models/partner.rb

class Partner < ActiveRecord::Base
    set_table_name "vrls_partners"
    set_primary_key "partner_id"
    has_many :listing
    has_many :customer
    has_one :listing_image
end

app/models/listing_image.rb

class ListingImage < ActiveRecord::Base
    set_table_name "vrls_listing_images"
    set_primary_key "listing_id"
    belongs_to :listing
end

app/models/listing_status.rb

class ListingStatus < ActiveRecord::Base
    set_table_name "vrls_xref_listing_status_code"
    set_primary_key "listing_status_code"
end

app/models/listing_type.rb

class ListingType < ActiveRecord::Base
    set_table_name "vrls_xref_listing_type"
    set_primary_key "listing_type_code"
end

app/models/listing_offer_type.rb

class ListingOfferType < ActiveRecord::Base
    set_table_name "vrls_xref_listing_offer_type"
    set_primary_key "listing_offer_type_code"
end

Start server. (To stop the server, type CTRL-C.)

$ script/server

Go to http://localhost:3000/listings in your Web browser. Try the "show", "edit", and "new" pages as well.
Make the edits described in Section 11.3.5 of the book to watch the application "evolve". Revisit the various pages to see how they've changed.
Once you are satisfied with the state of the application, you can run it in production mode, against the already established database used by the main VRLS application. Before doing this, edit the config/database.yml file to change the production database name to "vrls" (which was the name given to the database used by the main application).

development:
  adapter: mysql
  encoding: utf8
  reconnect: false
  database: vrlsadmin_development
  pool: 5
  username: root
  password: your-mysql-root-password
  host: localhost

# Warning: The database defined as 'test' will be erased and
# re-generated from your development database when you run 'rake'.
# Do not set this db to the same as development or production.
test:
  adapter: mysql
  reconnect: false
  database: vrlsadmin_test
  pool: 5
  username: root
  password: your-mysql-root-password
  host: localhost

production:
  adapter: mysql
  reconnect: false
  database: vrls
  pool: 5
  username: root
  password: your-mysql-root-password
  host: localhost

Then start the server in production mode. With the application pointing to the production database, any changes made via the main application (e.g., new user signups and profile updates) will be reflected in the admin interface.

$ nohup script/server -e production 2>&1 >/dev/null &