MKDoc 1.6  installation instructions
====================================

MKDoc is a web-based content management system, it is an apache mod_perl
application using a mysql backend.

MKDoc runs on unix or a unix-like system such as linux.  Previous
versions of MKDoc have been successfully installed on Windows, however
this is unsupported and not very practicable.

These instructions are suitable for the installation of a test version
of MKDoc, production servers may involve different configurations.


Upgrading to MKDoc-1.6.31
-------------------------

If you are upgrading from a version of MKDoc 1.6 prior to 1.6.31,
you will need to update your databases because of the new TimeRange
and Group functionality.

You can do this by running the 'update_db.pl' script for each site
like so:

   source /var/mkdoc/example.com/mksetenv.sh
   /usr/local/lib/mkdoc-1.6/update_db.pl

Make sure you backup your databases first.

Similarly, you can upgrade links components to the new format that
differentiates between internal and external links (this is
recommended, but not essential):

   source /var/mkdoc/example.com/mksetenv.sh
   /usr/local/lib/mkdoc-1.6/update_links.pl


Basic requirements
------------------   

Install perl, apache, mod_perl and mysql if they are not already   
installed.

MKDoc has been tested with mysql-3 or 4, apache-1.3.33 and mod_perl-1.29,
though any recent version of these packages should work.

Apache-2 is not supported as an MKDoc platform (see the
MP2_HOWTO.TXT instructions if you want to experiment).  However, a
recommended configuration is to run MKDoc on a 'back-end' apache
1.3.x process with a front-end apache-2 acting as a proxy.

MKDoc-1.6 requires perl-5.8.0 or later, this is essential for unicode
support.


Packages required
-----------------

Install htmltidy: http://tidy.sourceforge.net/

MKDoc sends email to contact users and editors and will expect that
the host server is capable of routing email through the standard
/usr/sbin/sendmail interface.

If you do not have a sendmail tool in /usr/sbin, you may have to
create a link to the actual location:

    ln -s /usr/lib/sendmail /usr/sbin/

Install all the perl modules in MODULES.TXT, currently these modules are
required:

(Note, the redhat packages: perl-MIME-Base64 perl-XML-Parser perl-DBI
perl-DBD-MySQL perl-DateManip ImageMagick-perl are ok for the first six).

    DBI
    DBD::mysql
    Date::Manip
    MIME::Base64        (not required when using perl-5.8.1 or later)
    Image::Magick       (5.5.8 or greater required)
    XML::Parser

(the remaining packages can be found on CPAN)

    Text::Unidecode
    Text::CSV_XS
    Unicode::String
    Mail::IMAPClient
    Time::ParseDate     (part of the Time-modules package)
    XML::RSS
    Cache::Cache
    Crypt::PassGen
    Mail::CheckUser
    Getopt::Declare
    Geography::Countries
    Petal
    Petal::Mail
    MKDoc::XML
    MKDoc::Control_List
    MKDoc::Text::Structured
    DateTime
    DateTime::TimeZone


Getting the MKDoc code
----------------------

You can download a version of MKDoc from: http://download.mkdoc.com/

Extract your MKDoc tarball somewhere useful like:

    /usr/local/lib/mkdoc-1.6

Note that if you choose a different installation directory, the
paths and commands in the following instructions will need to be
altered accordingly.


Configuring your MKDoc system
=============================

1. Change to your mkdoc directory:

      cd /usr/local/lib/mkdoc-1.6

2. Initialise the server-wide MKDoc configuration file:

      tools/install-mkdoc.pl

   From now onwards, you will need to source this shell
   configuration file to preset MKDoc environmental variables before
   you can run any MKDoc commands-line tools or start/restart
   apache:

      source /usr/local/lib/mkdoc-1.6/mksetenv.sh

   (You will want to add this line to whichever script you use to
   start apache)

   Note that 'source' is a bash built-in command.  If you use a
   different shell, then you will either need to create appropriate
   files to set the environmental variables or switch to bash while
   running mkdoc tools or starting apache.

3. Make sure the (initially empty) MKDoc specific httpd.conf file is
   included by the system /etc/httpd/conf/httpd.conf by adding an
   Include line in the VirtualHosts section.

   ie. locate this line (it may need uncommenting if it is commented
   out):

      NameVirtualHost *

   ..and add this line after it (you will have to do this as user
   'root'):

      Include /usr/local/lib/mkdoc-1.6/conf/httpd.conf

4. Restart apache.  Apache doesn't pick-up changes to configuration
   files automatically, so you need to restart the apache server after
   every change.  As root, type:

      /sbin/service httpd restart

   (This command will be different if you have built your own apache)


Setup the indexing cron job
---------------------------

MKDoc documents are indexed for searching by a separate indexing
tool, this tool indexes all MKDoc sites at once.  The program should
be run as cron job at a suitable interval, such as once an hour:

    # index all MKDoc sites every hour on the hour, threshold 90 minutes
    0 * * * * source /usr/local/lib/mkdoc-1.6/mksetenv.sh && 010..indexer.pl 5400

(This can be run as either a normal user or as the same user as the
webserver itself)


Setup the RSS newsfeed cron job
-------------------------------

MKDoc pages can be configured to fetch RSS newsfeeds and embed them
within the document as headlines, this fetching task uses two
separate tools managed by cron.  One tool runs at frequent
intervals, doing the initial fetching and resolving problems; the
second tool runs at longer intervals doing all the routine updating.

Important: This cron job needs to be run as the same user as the
webserver itself (or a user that has appropriate permissions to
overwrite files created by the webserver):

    # run the RSS troubleshooter three times an hour, thirty-six
    # failures and the feed is permanently abandoned
    0,20,40 * * * * source /usr/local/lib/mkdoc-1.6/mksetenv.sh && 030..rss_troubleshooter.pl 36

    # run the routine RSS updater at eleven every morning
    0 11 * * * source /usr/local/lib/mkdoc-1.6/mksetenv.sh && 031..rss_routine.pl


Creating an MKDoc web-site
==========================

Now you can start creating MKDoc sites.


Creating the database
---------------------

Create the mysql database that you are going to use (important, you will
have to use real values for User, Password and Db):

    mysql -uroot mysql

    INSERT INTO user (Host, User, Password) VALUES ('localhost',
    'mkdoc1', password ('mkdoc1'));

    CREATE database mkdoc1;

    INSERT INTO db (Host, Db, User, Select_priv, Insert_priv,
    Update_priv, Delete_priv, Create_priv,Drop_priv, Grant_priv,
    References_priv, Index_priv, Alter_priv) VALUES ('localhost', 'mkdoc1',
    'mkdoc1', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y');

    flush privileges;

For mysql-4.x the db line needs to have two extra entries:

    INSERT INTO db (Host, Db, User, Select_priv, Insert_priv,
    Update_priv, Delete_priv, Create_priv,Drop_priv, Grant_priv,
    References_priv, Index_priv, Alter_priv, Create_tmp_table_priv,
    Lock_tables_priv) VALUES ('localhost', 'mkdoc1', 'mkdoc1', 'Y', 'Y',
    'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y');

If you need to use a non-local mysql server, then your configuration
will be different - Consult your mysql documentation.


Setting up the DNS
------------------

Create two hostnames that will be used for the two different MKDoc
interfaces, we suggest that they are given names like:

    www.example.com
    users.example.com

If you only want to try-out MKDoc locally and have no access to a dns
server to create new hostnames, you can simply add them to your local
/etc/hosts file (change 10.0.0.1 to your actual ip-address):

    10.0.0.1     www.example.com
    10.0.0.1     users.example.com


Install the MKDoc site
----------------------

By default, files for a site live in a folder named after the domain
name of the site.  So if your domain is called example.com, the
public and user domains would be called www.example.com and
users.example.com - The folder on the server would be called
something like /var/mkdoc/example.com.

(from now on this document will refer to this as "$SITE_DIR")

Note that /var/mkdoc needs to be writable by whichever user account
is doing the installation.

1. Initialise the MKDoc environmental variables:

      source /usr/local/lib/mkdoc-1.6/mksetenv.sh

2. Create an MKDoc site by running the install script and telling it
   where to install the site-specific files:

      install-site.pl /var/mkdoc/example.com

3. Now use the menu system to configure your site; you will be asked
   to input your database details and some general information about
   your first site.

   MKDoc will generate an admin password, keep a record of this as
   you will need it to add users and perform other administration.

4. Restart apache, as root, type:

      /sbin/service httpd restart

You should now be able to log-on to your MKDoc site using the
initial user accounts you configured earlier and start creating
content.


Resetting permissions
---------------------

Typically a web-server on a system uses a unique user account, often
this user is called 'nobody' or 'wwwuser'.  This means that when
MKDoc itself needs to access files on the filesystem it is going to
be using that system account to do it.

In order to ensure that these files are usable by MKDoc, the site
installation procedure makes some directories usable by anyone on
the system - This needs to be changed if the server has other,
untrusted users.

Find-out which account your web-server uses by looking at the 'User'
and 'Group' directives in the master httpd.conf file.

For example, if your 'User' is 'wwwuser' and your 'Group' is
'wwwgroup', you will need to run these commands as root to make
these directories only writable by the web-server:

  chown -R wwwuser:wwwgroup $SITE_DIR/static/files
  chown -R wwwuser:wwwgroup $SITE_DIR/static/images
  chown -R wwwuser:wwwgroup $SITE_DIR/data
  chown -R wwwuser:wwwgroup $SITE_DIR/cache

  chmod -R o-w $SITE_DIR/static/files
  chmod -R o-w $SITE_DIR/static/images
  chmod -R o-w $SITE_DIR/static/data
  chmod -R o-w $SITE_DIR/static/cache

Similarly, the database connection details need only to be readable
by the web-server:

  chown wwwuser:wwwgroup $SITE_DIR/su/driver.pl
  chmod 0440 $SITE_DIR/su/driver.pl


Setup the Newsletter cron job
-----------------------------

Registered users of MKDoc sites can request periodic newsletters
informing them of new documents that match their interests.

Unlike the search and RSS tools, you need to create cron entries for
each of your sites.

(This can be run as either a normal user or as the same user as the
webserver itself)

    # daily newsletter at 8am every morning
    0 8 * * * source /var/mkdoc/example.com/mksetenv.sh && 020..newsletter.pl day

    # weekly newsletter at ten past eight every monday morning
    10 8 * * mon source /var/mkdoc/example.com/mksetenv.sh && 020..newsletter.pl week

    # monthly newsletter at twenty past eight on the first day of every month
    20 8 1 * * source /var/mkdoc/example.com/mksetenv.sh && 020..newsletter.pl month


Final notes
===========

Online documentation is available here: http://www.mkdoc.org/docs/ 

Any further questions regarding MKDoc setup and administration can
be posted to the mkdoc-dev mailing list, you can subscribe here:
http://www.mkdoc.org/lists/mkdoc-dev/ 


Document Author
---------------

2005-09-01  Bruno Postle <bruno@mkdoc.com>

