Instructions for Downloading and Installing the Administrative Interface Application (Windows)

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 Linux, Unix, and Mac OS X environments 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 page on Installing Ruby on Rails on Windows is a useful resource.
  1. First, download and install Ruby. The simplest approach is to use the One-Click Ruby Installer for Windows (http://rubyinstaller.rubyforge.org/wiki/wiki.pl or http://rubyforge.org/frs/?group_id=167), which includes both the Ruby language interpreter and the RubyGems package manager, but will require additional steps to install Rails and other associated packages. (Make sure you check the box labeled "Enable RubyGems" when running the installer.)
  2. Make sure the Ruby executables were added to your command "path" settings during installation by typing path at a DOS command prompt. If the string presented by this command includes "C:\Ruby\bin", you are fine. If not, add this directory to the command path by entering the following:
    C:\Users\yourname> PATH=C:\Ruby\bin;%PATH%
    
    To add C:\Ruby\bin to your command path permanently:
    • Open the System control panel.
    • Click on the Advanced tab.
    • Click on the Environment Variables button.
    • Select the line in the System Variables window labelled Path and click the Edit button.
    • Add the following at the end of the text in the Variable Value box:

        ;C:\Ruby\bin
    • Click "OK" to dismiss this editing dialog.
    • Then click "OK" again to dismiss the Environment Variables window.
    • Finally, click "OK" one more time to confirm the System Properties changes.
  3. Make sure all the Ruby components are up to date, by entering the following command from a DOS Command Prompt:
    C:\Users\yourname> gem update --system
    Updating RubyGems
    Updating rubygems-update
    Successfully installed rubygems-update-1.3.3
    Updating RubyGems to 1.3.3
    Installing RubyGems 1.3.3
    Installing RubyGems
    
         ...
    
    RubyGems installed the following executables:
            c:/ruby/bin/gem
    
    If you see a line at the end of the output that looks something like

    '" update --system' is not recognized as an internal or external command, operable program or batch file.

    it can be ignored.

    Also, if you see this error when you run gem:

        No such file or directory - H:/

    execute the following command before attempting to run it again:

        C:\Users\yourname> set HOMEDRIVE=C:

    (A drive letter other than "H" may be displayed in the error message.) This is caused by a bug in Ruby Installer version 1.8.6-27 and can also be circumvented by using the more stable 1.8.6-26 release.
  4. Then install Rails using the following command:
  5. C:\Users\yourname> 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
    
  6. 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 Rails wiki and follow the instructions there.
  7. What has worked for us in a Windows environment is a two-step process.
    1. Execute the gem command to install the MySQL gem:

      C:\Users\yourname> gem install mysql --no-ri --no-rdoc
    2. Copy the 5.0 version of MySQL's libmySQL.dll file into the C:\Ruby\bin directory. This file can be downloaded from here.

    The second step is necessary because Ruby's MySQL gem does not work properly with the version of this DLL that comes with MySQL 5.1.
  8. 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.
  9. C:\Users\yourname> mkdir rails_apps
    C:\Users\yourname> cd rails_apps
    C:\Users\yourname\rails_apps> rails -d mysql vrlsadmin
          create  
          create  app/controllers
          create  app/helpers
          create  app/models
          create  app/views/layouts
          create  config/environments
              ...
    C:\Users\yourname\rails_apps> cd vrlsadmin
    C:\Users\yourname\rails_apps\vrlsadmin> 
    
  10. Edit the database configuration file (config/database.yml) - make sure the "mysql" adapter is enabled and provide appropriate credentials.
  11. 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
    
  12. 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.)
  13. C:\Users\yourname\rails_apps\vrlsadmin> 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
        ...
    
  14. Run the "script/generate scaffold" commands to build model/view/controller scaffolding for objects.
  15. NOTE TO WINDOWS USERS:
    In Windows, "script/generate ..." commands must be entered as "ruby script\generate ...".

    C:\Users\yourname\rails_apps\vrlsadmin> ruby 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
            ...
    
    C:\Users\yourname\rails_apps\vrlsadmin> ruby 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
           ...
    
    C:\Users\yourname\rails_apps\vrlsadmin> ruby 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
           ...
    
    C:\Users\yourname\rails_apps\vrlsadmin> ruby 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
           ...
    
    NOTE: The commands listed above can be downloaded as a single .bat file for execution on your desktop by right-clicking on this link and selecting the appropriate option for file download in your browser. For convenience, you will probably want to place the file in the directory your DOS command shell window is currently pointing to.
  16. Run "script/generate model" commands to build model/view/controller scaffolding for auxiliary objects.
  17. C:\Users\yourname\rails_apps\vrlsadmin> ruby script\generate model ListingType
           ...
    
    C:\Users\yourname\rails_apps\vrlsadmin> ruby script\generate model ListingOfferType
           ...
    
    C:\Users\yourname\rails_apps\vrlsadmin> ruby script\generate model ListingStatus
           ...
    
    NOTE: The commands listed above can be downloaded as a single .bat file for execution on your desktop by right-clicking on this link and selecting the appropriate option for file download in your browser. For convenience, you will probably want to place the file in the directory your DOS command shell window is currently pointing to.
  18. Edit model definition files (app/models/*.rb) to point to correct table names and primary key columns.
  19. 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
    
  20. Start server
  21. C:\Users\yourname\rails_apps\vrlsadmin> ruby script\server
    
  22. Go to http://localhost:3000/listings in your Web browser. Try the "show", "edit", and "new" pages as well.
  23. 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.
  24. 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).
  25. 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
    
  26. 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.
  27. C:\Users\yourname\rails_apps\vrlsadmin> ruby script\server -e production