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.


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

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

MKDoc has been tested with mysql-3.23, apache-1.3.27 and mod_perl-1.27,
though any recent version of these packages should work.

MKDoc hasn't yet been tested with apache-2 and probably will not run
out-of-the-box without modification.

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


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

You can download a version of MKDoc for TRIAL PURPOSES ONLY from:

     http://download.mkdoc.com/

Extract your MKDoc tarball somewhere useful like
/var/www/mkdoc/mkdoc-1.6


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

Your mysql server needs to be running before you can create an MKDoc
database; for redhat linux, you may need to issue the following commands
as root to start the server and ensure that it restarts when the server
is rebooted:

    /sbin/service mysqld start
    /sbin/chkconfig mysqld on

Consult your operating system documentation for other configurations.
If this is a production server, you will need to ensure that mysql is
secure.

If you don't require network access to your mysql server, you may want
to bind it to the loopback interface only; do this by adding a line to
the [mysqld] section of your /etc/my.cnf file:

    bind-address=127.0.0.1

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;

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 three 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


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

Install htmltidy:

    http://tidy.sourceforge.net/

If you intend to use the discussion component, you will need access to
an imap account to store messages.  This can be a separate server on the
same network or can be installed on the same machine as MKDoc.

We recommend Courier-IMAP as a suitable imap server:

    http://www.courier-mta.org/download.php#imap

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 (Note that this doesn't have to be the
Sendmail MTA, other MTAs such as Postfix or Exim also provide
/usr/sbin/sendmail).

If you do not have a sendmail tool in /usr/sbin, you may have to
create a link to another 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
    XML::Parser

(the remaining packages can be found on CPAN)

    Text::Unidecode
    Unicode::Normalize  (not required when using perl-5.8.1 or later)
    Unicode::String
    Mail::IMAPClient
    HTML::TreeBuilder
    Time::ParseDate
    XML::RSS
    Cache::Cache
    Getopt::Declare
    Time::ParseDate
    Geography::Countries
    Petal
    Petal::Mail
    MKDoc::XML
    MKDoc::Control_List


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

1. Change to your mkdoc directory:

      cd /var/www/mkdoc/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:

      source /var/www/mkdoc/mkdoc-1.6/mksetenv.sh

   (You may want to add this line to your profile)

3. Make sure the 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 /var/www/mkdoc/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

   You can ensure that the web server is restarted if the machine is ever
   rebooted by issuing this command:

      /sbin/chkconfig httpd on


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 /var/www/mkdoc/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 /var/www/mkdoc/mkdoc-1.6/mksetenv.sh && 030..rss_troubleshooter.pl 36

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


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

Now you can start creating MKDoc sites.

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/www/mkdoc/example.com.

1. Initialise the MKDoc environmental variables:

      source /var/www/mkdoc/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/www/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.


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/www/mkdoc/example.com/mksetenv.sh && 020..newsletter.pl day

# weekly newsletter at ten past eight every monday morning
10 8 * * mon source /var/www/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/www/mkdoc/example.com/mksetenv.sh && 020..newsletter.pl month


Final notes
-----------

Online documentation is available here:

    http://mkdoc.com/help/

Any further questions regarding MKDoc setup and administration can be
posted to the mkdoc-admin mailing list, you can subscribe here:

    http://lists.webarch.co.uk/mailman/listinfo/mkdoc-admin

-- 
2004-01-21  Bruno Postle <bruno@mkdoc.com>

