+
−= Litmus Installation Instructions =
+
−
+
−== Server Requirements ==
+
−
+
−We're using RHEL4/5 here at Mozilla, but any setup that will give you Apache+mod_perl+MySQL should be able to do the job.
+
−
+
−Specifically, you'll need:
+
−* Apache 2
+
−* MySQL 5 (4 should also work)
+
−* mod_perl 2 (optional)
+
−* sendmail (optional): for sending report via email
+
−
+
−== Required Perl Modules ==
+
−
+
−Apache::DBI - if mod_perl is being used
+
−Cache::Memcached::Fast (optional)
+
−CGI
+
−Class::DBI 
+
−Class::DBI::mysql 
+
−Class::DBI::Pager
+
−Class::DBI::Plugin::RetrieveAll
+
−Class::DBI::Search::Basic
+
−Data::Dumper
+
−Data::JavaScript
+
−Date::Manip
+
−DBIx::ContextualFetch
+
−Encode
+
−File::Find
+
−Getopt::Long
+
−HTML::StripScripts
+
−HTML::StripScripts::Parser
+
−JSON (version>=2)
+
−JSON::XS
+
−JSON::PP
+
−Sys::Hostname
+
−Template 
+
−Test::Harness
+
−Text::Markdown
+
−Time::HiRes
+
−Time::Piece 
+
−Time::Piece::MySQL 
+
−Time::Seconds
+
−XML::XPath
+
−utf8
+
−
+
−== Setting up the database ==
+
−
+
−If this is your first time installing Litmus, run populatedb.pl. 
+
−
+
−  cd litmus
+
−  ./populatedb.pl
+
−
+
−The populatedb.pl script will initially create a template configuration file, 
+
−'localconfig,' that contains variables to hold your database configuration 
+
−information. Edit the newly created 'localconfig' file with your database 
+
−configuration. Once 'localconfig' is populated with your database information, 
+
−run the populatedb.pl again with the '-r' flag to populate the initial lookup 
+
−tables (products, locales, etc) with sensible defaults (which you can adjust 
+
−later, if necessary). This will allow you to start using Litmus right away. 
+
−There is no UI at present for doing this.
+
−
+
−  vi localconfig
+
−  ./populatedb.pl -r
+
−
+
−NOTE: The default database name is 'litmus.' If you want to change this, 
+
−you'll need to change the name in populatedb.sql *AND* localconfig before 
+
−running the above commands.
+
−
+
−You'll then want to run "make install" to pre-compile your templates, verify
+
−your database setup, and prepare you Javascript libraries.
+
−
+
−  make install
+
−
+
−Then just pop the whole thing into a directory where your web server can
+
−get at it. Have fun!
+
−
+
−== Creating the first admin user ==
+
−
+
−To get yourself an administrator account, you'll need to load up Litmus in your 
+
−web browser and follow the link to create a new account. You'll have been 
+
−lucky enough to score user id number 2 (#1 is reserved for the anonymous 
+
−web-tester account, generally unused now). Grant yourself admin rights by 
+
−loading up mysql, connecting to your Litmus database, and running the 
+
−following command:
+
−
+
− mysql -u litmus -p litmus
+
− mysql> insert into user_group_map values ('2', '1');
+
−
+
−From there, you can go into "Edit Users" in the web interface and grant 
+
−rights to any new users. 
+
−
+
−== Sending mail from Litmus ==
+
−
+
−Sendmail (or a mailer with a compatible command-line interface) is required if
+
−you want Litmus to be able to send email, e.g. for daily reports. If you will
+
−be using something other than sendmail, you may need to change Litmus::Mailer
+
−appropriately.
+
−
+
−== Minimizing Javascript libraries ==
+
−
+
−The Javascript libraries included with Litmus are broken into 
+
−logically-separate files. Prior to install, we combine many of these files 
+
−together into a single, larger file. This results in a larger initial 
+
−download for your user but the file is then cached and subsequent access will
+
−be faster.
+
−
+
−We also use jsmin (http://javascript.crockford.com/jsmin.html) if it is in
+
−your $PATH to strip the Javascript and reduce their size as much as possible.
+
−
+
−This is done as part of the "make install" process, but you can do this by 
+
−hand too from your root Litmus install:
+
−
+
−  scripts/minify_js.bash 
+
−
+
−== Optional: Memcache ==
+
−Some queries can be cached in memcache, which will especially reduce stats
+
−lookup times. In order to activate memcaching, run a memcached server, then
+
−define $memcache_settings appropriately in localconfig.
+
−
+
−For a list of available settings, consult
+
−http://search.cpan.org/dist/Cache-Memcached-Fast/lib/Cache/Memcached/Fast.pm
+
−
+
−To disable memcaching, comment out the settings.
+
−
+
−== Things to do after an upgrade ==
+
−
+
−After upgrading Litmus from CVS, it's a good idea to run "make install" 
+
−again to pick up any schema changes that may have occured.