root/trunk/doc/INSTALL.txt @ 857

Welcome!
--------
Installing LiveJournal should be extremely simple.  If it's not, then
we consider it a bug and you should report it.  Email
bradfitz@livejournal.com with any questions or errors you find in this
document.


Assumptions
-----------
We're going to assume that:

 -- you have basic Unix skills.  
 -- you can install Apache
 -- you can install MySQL

We'll walk you through everything else, including configuring Apache
and MySQL for LiveJournal.


Conventions
-----------
Through this document we'll use the following conventions.  To run a
command as a normal user (usually user 'lj'), we'll use a normal shell
prompt character '$'. 

    $ example

To run a command as root we'll use a hash:

    # apachectl graceful


Creating an 'lj' user  (optional)
---------------------
If you want the LiveJournal code to run as a user other than what your
webserver runs as, then you'll need suEXEC support in Apache.  You're
free to figure that out yourself.  We'll assume your webserver is
running as user 'lj', though it doesn't have to run as any certain
user to work.

If you do use suEXEC, you'll need a User directive in your livejournal
Vhost, as well as some different options to start the FastCGI process.
You can read more about that at www.fastcgi.com.

Installing the files
--------------------
In the past, the mandatory path for Livejournal was /home/lj/ but that
isn't true anymore.  However, since that's where most people install
it, we'll assume that's where it is for the rest of this document.

  # mkdir /home/lj
  # chown lj.lj /home/lj

Note that the tarball creates a directory ("LiveJournal-YYYYMMDD"), so you'll
either want to untar at /home/ and then rename that directory to be lj, or
do something like:

   $ cd /home/lj
   $ tar zxvf LiveJournal-YYYYMMDD.tar.gz
   $ mv LiveJournal-YYYYMMDD/* .
   $ rm -r LiveJournal-YYYYMMDD

Perl modules:
-------------
LiveJournal requires several Perl modules to be installed.
Installing these modules requires a fully working perl and C development
environment (including gcc and make).

If you are unfamilar with installing modules, the simplest method is to enter
the following command from a root shell prompt:

   # perl -MCPAN -e shell

Once the Perl interpreter has loaded (and been configured), you can install
modules by issuing the command 'install MODULENAME'.

The first thing you should do is upgrade your CPAN:

   cpan> install Bundle::CPAN

Once it's done, type:

   cpan> reload cpan

Now, install the following modules:

        Bundle::libnet
        Digest::MD5
        Image::Size
        FCGI
        MIME::Lite
        Compress::Zlib
        MIME::Base64
        URI::URL
        HTML::Tagset
        HTML::Parser
        LWP::Simple
        LWP::UserAgent
        Time::DaysInMonth
        GD
        GD::Graph
        GD::Text
        Bundle::Mysql
        Mail::Address
        Proc::ProcessTable
        SOAP::Lite
        Unicode::MapUTF8

If you're using Debian this should get everything:

# apt-get install libwww-perl libfcgi-perl libmime-lite-perl \
                  libsoap-lite-perl libgd-perl liburi-perl \
                  libimage-size-perl libdbd-mysql-perl libdbi-perl \
                  libnet-perl libdigest-md5-perl libgd-graph-perl \
                  libgd-text-perl libcompress-zlib-perl \
                  libunicode-maputf8-perl libproc-process-perl \
                  libapache-mod-fastcgi

NOTE: there used to be three custom LJ:: modules that needed
installing.  We no longer install those in the system.  Instead LJ
uses them right out of ~lj/cgi-bin/LJ/*.  If you have those old LJ
modules installed, it's best to go remove them since Perl will prefer
system-level ones over local ones.

Apache Modules:
---------------
You'll need the following Apache modules running (either statically or
as DSOs):

Standard:
        mod_env
        mod_setenvif
        mod_alias
        mod_expires
        mod_actions
        mod_rewrite
        mod_mime_magic
        mod_mime

Special:
        mod_fastcgi     -- from http://www.fastcgi.com/

NOTE: It is critical that mod_mime_magic appear in the Apache config
      file before mod_mime, otherwise none of the LiveJournal pages
      will work. See http://httpd.apache.org/docs/mod/mod_mime_magic.html
      if you'd like more information.


Configuring Apache
------------------
You need to add a <VirtualHost> section in Apache's httpd.conf file.
See INSTALL.apache.txt for an example that you'll only need to modify
slightly (only the hostname).


Making a MySQL database for livejournal
---------------------------------------
First, are you running a recent MySQL?  You should be at least
3.23.38, especially if you'll be running a high-volume LJ site with
replication.  If you're running 3.23.x, you'll probably be okay.  If
you're running 3.22.x, you definitely need to upgrade.

Login to MySQL as the root MySQL user and create the database that
will hold the LiveJournal data:

     $ mysql -uroot -p

     mysql> CREATE DATABASE livejournal;
     mysql> GRANT ALL PRIVILEGES ON livejournal.* TO 
             lj@'127.0.0.1' IDENTIFIED BY 'ljpass';

You can change the usernames and passwords above.  We'll set those in
ljconfig.pl in a moment.


Setting up LJHOME environment variable
--------------------------------------
Be aware that nearly all LiveJournal code depends on the $LJHOME
environment variable being set to the top-level directory that
LiveJournal is installed at.

The Apache configuration in INSTALL.apache.txt has the necessary
directives to make sure the web code always has $LJHOME set, but if
you're running LJ maintenance commands from a terminal, you'll need to
make sure $LJHOME is set for yourself.

The easiest way is to put the following in your ~/.bash_profile:

    LJHOME=/home/lj; export LJHOME

This is assuming you use bash.  If that doesn't work and you don't
know what your shell reads on start-up, try ~/.profile.

Test that it's set:

    $ . ~/.bash_profile
    $ echo $LJHOME

You should see it spit out /home/lj (or whatever you set it
to... depending on where you installed the code).


Configuring LiveJournal
-----------------------
You need to make a LiveJournal configuration file.  There's an example
ljconfig.pl in the doc directory by the name of "ljconfig.pl.txt".
You need to copy this file to cgi-bin/ljconfig.pl and then edit it to
suit your needs.

   $ cd /home/lj
   $ cp doc/ljconfig.pl.txt cgi-bin/ljconfig.pl

The reason it's not there already is so that future upgrades don't
destroy your configuration.  The end of ljconfig.pl reads in
ljdefaults.pl so that if we add new options, ljdefaults.pl will be
updated and will set sane defaults.  After an upgrade you want to
glance at ljdefaults.pl (or the original doc/ljconfig.pl.txt) and see
if there are any new options.


Populating the Database
------------------------
This is almost the final step to having a fully working LJ database,
and it is one of the easiest.

Assuming you've done everything above, all you have to do is:

   $ cd /home/lj
   $ bin/upgrading/update-db.pl --runsql --populate

That'll bring your database schema up-to-date and populate it with any
look-up data it needs.


Installing the crontabs
-----------------------
From the LiveJournal user account (or whatever user is running LJ),
you need to install some crontabs.  These are periodic commands that
run and manage your LiveJournal installation.

Type:

    $ crontab -e

This will bring up either your $EDITOR, or vi.  If you want to set
your editor explicitly, do:

    $ EDITOR=pico crontab -e

[Note: prolonged use of pico can cause insanity.  You are encouraged
       to learn emacs or vi.]

Now, enter the following stuff between the dotted lines below.  Not
all of it is necessary.  See the comments below.  The LJHOME= line is
required.  See the section above about how the $LJHOME environment
variable is required everywhere.  This is another place.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LJHOME=/home/lj
MAILTO=youremail@wherever.com

# Essential:
* * * * * /home/lj/bin/ljmaint.pl db_batchdelete >/dev/null
* */12 * * * /home/lj/bin/ljmaint.pl clean_caches >/dev/null

# Optional, if you want birthday mail, and the random user feature:
# (you can remove parts)
5 1 * * * /home/lj/bin/ljmaint.pl bdaymail build_randomuserset >/dev/null

# If you want statistics:
30 1 * * * /home/lj/bin/ljmaint.pl genstats genstatspics >/dev/null
5 2 * * 0 /home/lj/bin/ljmaint.pl genstats_weekly > /dev/null

# If you're running a high-load site with $LJ::BUFFER_QUERIES on,
# there's another one to install:
*/5 * * * * /home/lj/bin/qbufferd.pl >/dev/null
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

If query buffering is off, you can still run that, but it's not
needed.  Packagers should make their packages install it, since
it doesn't hurt if it's running and not used.  It'll die off
right away if it realizes it's not needed.  Otherwise it'll 
start up in the background and run every 10 seconds or so.
Future startups by cron will only make sure it hasn't died (like
if the database dies).


Finishing up
------------
You should now just about have a working LiveJournal
installation. There are many things you can still do, but all are
outside the scope of this document.

If you haven't restarted Apache, you'll want to do that now:

  # apachectl restart

The last thing you will need to do is create the system user that'll
have privileges to give privileges to other users.

  $ bin/upgrading/make_system.pl

It'll prompt you for the password to use for the system account and
then sets it all up.

You now have the ability to login to your LJ site as user "system"
with the password you set and then grant priviledges from the admin
section to other users:

  http://your-lj-server/admin/priv/

If you have any questions, join the "lj_dev" community on
LiveJournal.com and post your questions.  We'd love to help you out.


More reading
------------
It's recommended that you read the file "CVS.txt" for instructions on
how to stay up-to-date with the latest LiveJournal code.