Below are the steps necessary to get app_sample running (the newest version of the hub). The statements shown here have been tested on either Mac OSX or Windows. If you find anything that diverges from the instructions listed, please add your changes so this stays up to date for everybody else.

Setting Up A Development Environment

1. If you're on Windows...

   1. All the steps below, under "To do it by hand...", have been automated with a single Windows install .exe file.

   2. Get the file from here: http://kalivo.com/appsteam/files/

   3. Pick the version of the file that goes with the hub release you want to work on (typically, the latest file is right since you'll want the head of the codebase trunk).

   4. After you run this file, you should be in the same place you would have been if you followed the manual steps below.

2. To do it by hand...

   1. Download the following packages:

      1. subversion (latest stable) : http://subversion.tigris.org/

      2. ruby (1.8.6) : http://www.ruby-lang.org/en/downloads/

         1. NOTE: On the Windows installer, you CAN check "Enable RubyGems". This simply sets the RUBYOPT env variable for you so that Rubygems is always active when Ruby runs.

      3. mysql (5.0 stable) : http://dev.mysql.com/downloads/

         1. Note that, for now, the root passwd for the database needs to be "password12". Ideally this is fixed in the future such that database.yml isn't under version control.

      4. rubygems (latest stable) : http://rubygems.org/read/chapter/3

      5. If you are in OS X:

         1. Take a look at http://hivelogic.com/articles/2005/12/ruby_rails_lighttpd_mysql_tiger
            You will need to update it to the version we are using.

         2. When installing readline 5.2, you will need to patch it.  Look here:
            http://secretdiaryofhan.wordpress.com/2007/12/26/building-readline-52-on-os-x-leopard/

   2. Next, install the necessary ruby gems.

      1. You'll need to use sudo if you're on *nix.

      2. This script, ngen-gems-setup.sh, details things for you. If you have bash, then you can simply run it (it has been tested on Windows+Cygwin and Linux). Otherwise, run the "gem install" commands yourself, with versions, as shown in the script.

      3. The versions shown for each gem are from production systems. You MAY not want the latest possible version of every gem, so you should NOT run "gem update" unless you know what you are doing.

      4. SOME gems may prompt you to choose a particular platform type. Simply choose "mswin32" if you're on Windows, or whatever is proper for your system.

      5. When running the script (or the "gem install" commands in it):

         1. If you're on Linux, you'll probably need packages "ruby-devel" and "mysql-devel" also installed.

         2. If you have trouble with the MySQL gem, check:

            1. http://wiki.rubyonrails.org/rails/pages/Mysql+Connection+Problems

            2. On Linux or OS X, you might need to modify the MySQL install line in the script, which looks like:
               "gemInst 2.7 mysql -- ..."
               And change the paths if your MySQL install uses different ones.

            3. On OS X, you might have to do ONE of these:

               1. sudo gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
                  -OR-

               2. sudo gem install mysql -- --with-mysql-dir=/usr/local/mysql

   3. Next install Imagemagick for avatar processing. You need to install Imagemagick before installing the appropriate gem:

      1. Windows:

         1. Go here:  http://rubyforge.org/frs/?group_id=12&release_id=20692

         2. Download the RMagick-2.5.0-ImageMagick-6.4.1-5-Q8.zip file. It contains both Imagemagick and Rmagick.

         3. First, run the Imagemagick install .exe.

            1. Note: Make sure to check the "Add to system path" option. The RMagick gem will NOT work (probably won't even load) if the PATH variable isn't right.

         4. Then install the gem with this command:

            1. gem install rmagick-2.5.0-x86-mswin32.gem --local

            2. Note: If the gem fails to install with a 'buffer' error, try a different version of the RMagick-*.zip file.

      2. OS X:

         1. Install darwinports from: http://www.macports.org/install.php

         2. port install tiff -macosx imagemagick +q8 +gs +wmf (again, no space between the - and "macosx")

         3. gem install rmagick

      3. Linux:

         1. This should work, especially on Red Hat distros: sudo yum install ruby-RMagick

         2. If not, use your favorite package manager or head to:
            http://www.imagemagick.org/script/binary-releases.php
            And run:  sudo gem install rmagick

   4. Next install memcached

      1. For Windows:

         1. Download from:  http://jehiah.cz/projects/memcached-win32/

         2. Read the instructions on this web page to install it as a Windows service.

      2. For Red Hat-ish Linux: sudo yum install memcached; sudo service start memcached

      3. For other *nix, download the memcached server and run it on your box as a daemon. I do now know how to set this up on a mac:

         1. http://www.danga.com/memcached/

      4. You'll want it to run on ip 127.0.0.1 and port 11211 (should be the installer defaults anyway)

   5. After getting all your package installations in order, you can grab all the projects from svn:

      1. svn co svn://72.249.82.8/kalivo/trunk/ kalivo

      2. svn co svn://72.249.82.8/service_user/trunk/ service_user

      3. svn co svn://72.249.82.8/service_storage/trunk/ service_storage

      4. svn co svn://72.249.82.8/service_provision/trunk/ service_provision

      5. svn co svn://72.249.82.8/app_sample/trunk/ app_sample

      6. svn co svn://72.249.82.8/service_pubsub/trunk/ service_pubsub

   6. Now create your databases.

      1. For a mac, you can use CocoaMySql (http://cocoamysql.sourceforge.net/).

      2. For windows, you can use the MySQL GUI tools (http://dev.mysql.com/downloads/)

      3. The db (schema) names to create are:

         1. service_provision

         2. service_provision_test

         3. service_user

         4. service_user_test

         5. app_sample

         6. app_sample_test

         7. service_pubsub

         8. service_pubsub_test

   7. Now do some initialization and startup:

      1. The commands to run: ("#{source_root}" is your work dir, where you checked out all the svn projects)
         cd #{source_root}/service_provision
         rake db:migrate
         mongrel_rails start -p 3000 (in background or separate cmd prompt on Windows)
         cd #{source_root}/service_user
         rake db:migrate
         mongrel_rails start -p 3001 (in background or separate cmd prompt on Windows)
         cd #{source_root}/service_pubsub
         rake db:migrate
         mongrel_rails start -p 3004 (in background or separate cmd prompt on Windows)

      2. Notes:

         1. The "mongrel_rails start ..." for the provision service MUST be running FIRST before any other migrations.

         2. The pubsub migrate may not work. You can probably safely ignore it for now, and worry about fixing it up later.

      3. Some conveniences to manage your platform service processes...

         1. If you're on *nix:

            1. You can run this Ruby script (thanks @elarson):

               1. #!/usr/bin/env ruby

               2. commands = [

               3. "cd service_provision && mongrel_rails start -p 3003",

               4. "cd service_user && mongrel_rails start -p 3001",

               5. "cd service_pubsub && mongrel_rails start -p 3004" ]

               6. threads = [?]

               7. for command in commands

               8. threads << Thread.new(command) { |service_command|

               9. system(service_command)

               10. }

               11. end

               12. threads.each { |t| t.join }

            2. OR, use the ngen-svc script.

         2. Notes:

            1. The pubsub service may not start. You can probably safely ignore it for now, and worry about fixing it up later.

            2. Instead of "mongrel_rails start", in each case you can use Webrick by substituting:
               ruby script/server -p #{port}
               (the "-p nnnn" part stays the same)

            3. If you get an error that looks something like:
               #<NameError: uninitialized constant BSGPlatformService::ServiceXML::Zlib>
               Put in the top of the file causing the problem this line:
               require 'zlib'

         3. If you're on Windows, your ruby doesn't have threading. Blame @matz for that. In this case, you have a few other options:

            1. Start the services independently. In this case, run the commands in lines 3-5 of the sample Ruby script above.
               NOTE:  The provision service MUST always be first, and MUST be fully running, before any others are started.

            2. OR, create a Windows batch file that does it, and include it here (please!)

            3. OR, if you have Cygwin, there's a bash script called "ngen-svc" that starts up services, and can bounce them, or kill them. [If you don't have Cygwin, I highly recommend it, especially for any command line stuff.  -DH]

            4. OR, use the Windows installer .exe mentioned at the top, which creates Windows services for you.

3. Next you need to install CCTray (Windows) or CCMenu (OSX) or JCCMenu (any OS).

   1. Download and install it:

      1. OS X:  http://sourceforge.net/projects/ccmenu/

      2. Windows:  http://sourceforge.net/project/showfiles.php?group_id=71179&package_id=83198

      3. Linux-Gnome/OS X/Windows: http://jcctray.sourceforge.net/

      4. You only need CCTray or CCMenu, not all of CruiseControl.

   2. Configure it:

      1. CCTray:

         1. Go to "Build Projects" tab, and add a "build server" with a "custom HTTP URL" like this:
            http://ci.ngenplatform.com:3333/XmlStatusReport.aspx

      2. JCCTray:

         1. Server type is "CruiseControl.rb" and URL is "http://ci.ngenplatform:3333/".

      3. CCMenu: Check with Terry.

      4. Basic projects are:
         ContentService, Kalivo, KalivoSmoke, PubSubService, ServiceProvision, StorageService, UserService

4. After each service is running, you can finally start the hub application.

   1. Run these commands:

      1. cd #{source_root}/app_sample

      2. rake db:migrate

      3. mongrel_rails start

   2. Notes

      1. You MUST have mongrel installed for app_sample to work. Webrick won't let you log in.

      2. The "rake db:migrate" isn't needed every time. It's just for when the database needs to be initialized or updated.

      3. As of this writing, the app_sample codebase is broken. The db:migrate or mongrel_rails may not work. Get help from a teammate if this is the case, or, skip down to the "Setting Up A Production Hub" section.

   3. Point your browser to http://localhost:3000/, and be amazed.  :)

----

Setting Up A Production Hub

1. This part assumes you can already run the platform services as listed above in step #2.8.

2. You must also have checked out the kalivo project from svn, as above in step #2.6.

3. Now set up the hub, kalivo, with the nGenera theme.

   1. Go into your kalivo source dir.

   2. Apply the nGenera theme:

      1. rake kalivo:config:set THEME=ngenera

      2. rake theme_update_cache theme=ngenera

4. Next get the latest versions of the production database backup files.

   1. First, ssh to a proper box, one of these:

      1. 72.249.21.180

      2. OR 72.249.37.200

      3. OR 72.249.39.81

         1. If you're on Windows, and you use the regular Putty (which stores its profiles in the registry), then you can get the file attached to this page called:
            putty-profiles-ngenera.zip

         2. Unzip it, right-click the .reg file, and select "Merge". The next time you start Putty it will show all the nGenera server profiles.

      4. See Marc S or Mike R if you don't have the ssh login.

   2. Run these commands:

      1. cd /var/www/apps/database_backups

      2. ls -l

   3. Make a note of the latest version of each of these file patterns:

      1. app_sample_*

      2. ngenera_*

      3. service_provision_*

      4. service_pubsub_*

      5. service_user_*

   4. Use scp to copy each of the 5 files above to your box.

   5. Import the files.

      1. If the filename ends in .sql, run:

         1. mysql -uroot -ppassword12 < #{file_name}

      2. If the filename ends in .gz, run:

         1. gunzip < #{file_name} | mysql -uroot -ppassword12

5. Prepare the database files for your local environment.

   1. For the steps listed below, do the service_provision database FIRST.

   2. Make sure the provision service is already started before doing other tables. Other platform services are not needed for this part.

   3. The basic pattern for each database file is:

      1. Cd to the root of the project that depends on the given database.  E.g. the "ngenera" database is for the "kalivo" project with the "ngenera" config subdir.

      2. Run: rake db:migrate

      3. If the database is "ngenera" or any hub image, also run: rake kalivo:neuter clr=y

         1. Note: This step may fail the 1st time. If so, run it again, and it should work the 2nd time.

      4. If the database is "service_provision", also run: rake kalivo:neuter

      5. Repeat 1-4 for each database file you imported.

   4. Double-check the data before starting services.

      1. Start the MySQL query browser.

      2. Check the hub (e.g. "ngenera") database as follows.

         1. Make sure the "services" table is either (a) empty, or (b) contains references to "localhost" and not any production URLs. If this is not true, then:

            1. Run the query:  truncate services

            2. From the "service_provision" dir, again run: rake kalivo:neuter

         2. Make sure the "users" table has most of its emails prefixed with an "x". Some emails, like the ngenera.com and kalivo.com ones, should be untouched. If this is not true, there is a manual way to fix it, as follows:

            1. Start the kalivo application. See step #8 in the previous section, but change "app_sample" to "kalivo".

            2. Hit http://localhost:3000/account/login_under_duress and login as "tech-support".

            3. Then go to the admin section, under settings, change the root URL to "localhost:3000".

            4. Under transforms, go to the bottom and click "convert to development mode."

            5. Make sure that the users table is correct now (most should be preceded with an 'x').

6. Start up the remaining platform services. See step #2.8 in the previous section.

7. Start up the kalivo application. See step #3 in the previous section, but change "app_sample" to "kalivo".

8. Point your browser to http://localhost:3000/.

ngen-gems-setup.sh

ngen-svc

putty-profiles-ngenera.zip