= 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.