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