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.30 ------------------------- If you are upgrading from a version of MKDoc prior to 1.6.30, you will need to create a MySQL Document_TimeRange table for each of your sites beforehand. You can do this by running the 'timerange_update_db.pl' script for each site like so: source /var/www/mkdoc/example.com/mksetenv.sh perl /var/www/mkdoc/mkdoc-1.6/timerange_update_db.pl etc.. 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.31 and mod_perl-1.29, 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 from: http://download.mkdoc.com/ Extract your MKDoc tarball somewhere useful like: /var/www/mkdoc/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. 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::String Mail::IMAPClient Time::ParseDate 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 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) 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 /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. (from now on this document will refer to this as "$SITE_DIR") 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. 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/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 Setup MKDoc::Apache_Cache ------------------------- MKDoc-1.6 ships with an internal cacheing system that means that documents don't need to be constantly regenerated for every request. For anything more than a small site, you should investigate setting-up the superior MKDoc::Apache_Cache: http://mkdoc.com/docs/howtos/apache-cache/ 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-09-30 Bruno Postle