MkDoc 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 works fine on linux redhat-7.3 using the standard distributed rpm packages. MkDoc has been tested with redhat mysql-3.23, apache-1.3.23 and mod_perl-1.26, though probably any recent version of these packages will work. MkDoc requires perl-5.6.1 or later, this is essential for unicode support. Getting the code ---------------- You can download a verison of MkDoc for trial purposes only from: http://download.mkdoc.com/ Make sure you have both packages, 'mkdoc' and 'mkdoc-site'. Extract your MkDoc tarballs and place the two folders somewhere useful like /var/www/mkdoc/mkdoc and /var/www/mkdoc/mkdoc-site/ This creates two directories full of files: /var/www/mkdoc/mkdoc # the MkDoc server code /var/www/mkdoc/mkdoc-site # a single MkDoc web-site 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 MkDoc makes a lot of use of mysql. For anything other than a small site, the number of database connections can exceed the mysql defaults. Although tuning mysql is a separate subject, you may want to add the following lines to the [mysqld] section of the /etc/my.cnf file: set-variable = max_connections=500 set-variable = key_buffer=256M set-variable = max_allowed_packet=1M set-variable = table_cache=256 set-variable = sort_buffer=1M set-variable = record_buffer=1M set-variable = myisam_sort_buffer_size=64M set-variable = thread_cache=8 set-variable = thread_concurrency=2 skip-locking log-bin Consult the mysql documentation for other configurations. If this is a production server, you will need to ensure that mysql is secure. 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 three different MkDoc interfaces, we suggest that they are given names like: www.example.com editor.example.com admin.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 editor.example.com 10.0.0.1 admin.example.com Packages required ----------------- The first two packages require compiling with gnu 'gcc' and 'make'. Install the icu internationalisation library: http://oss.software.ibm.com/icu/download/2.1/icu-2.1.tgz Install htmltidy: http://tidy.sourceforge.net/ Install all the perl modules in MODULES.TXT, currently these modules are required: (Note, the redhat packages: perl-MIME-Base64-2.12 perl-XML-Parser-2.30 perl-DBI-1.21 perl-DBD-MySQL-1.2219 are ok for the first four). MIME::Base64 XML::Parser DBI DBD::mysql (the remaining packages can be found on CPAN) XML::RSS Text::Unidecode Unicode::String Unicode::Normalize Unicode::Transliterate (the last two can be found in the mkdoc/contrib/ folder) MKDoc-Apache-Auth-MySQL UTF8-Hack You can check for CPAN perl modules that may need upgrading or installing for MkDoc by running this script: /var/www/mkdoc/mkdoc/tools/checkcpan.pl Configuring your MkDoc site -------------------------- Open up mkdoc-site/install.conf in an editor and change the defaults to suit your new site: - Change the domain name section to match the names you have created in 'Setting up the DNS' above. - Complete the details to match your mysql database. - Change the details to suit your initial editor - It's important to change the password for this editor. Run the install script: perl install.pl /var/www/mkdoc If you get an error complaining about an Unknown table 'Document', don't worry, it's only a warning (if you run the script again you won't get the error). Setup the indexing cron job --------------------------- MkDoc documents are indexed for searching by a separate indexing application. This program should be run as cron job at a suitable interval, such as once an hour. This is a little script that can be used to reindex everything on your site that is less than 90 minutes old: #!/bin/sh cd /var/www/mkdoc/mkdoc/tools export SERVER_NAME=www.example.com export PATH_INFO=/ perl indexer.pl 1.5 > /dev/null Note that though you have to specify a valid MkDoc site in the SERVER_NAME part of the script, this script will index all the MkDoc sites on the server. Save it somewhere such as: /var/www/mkdoc/mkdoc/tools/mkdoc-indexer.sh ..and create a cronjob to run it once an hour: 0 * * * * /bin/sh /var/www/mkdoc/mkdoc/tools/mkdoc-indexer.sh Apache configuration -------------------- 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/conf/httpd.conf Further apache configuration ---------------------------- If you want to run MkDoc using mod_perl (recommended), uncomment the lines in the httpd.conf file that enable it: /var/www/mkdoc/mkdoc-site/httpd.conf You will also want to enable password protection for the su/admin interface in the same file. You should now be able to restart the apache server. As root, type: /sbin/service httpd restart You can ensure that the web server is restarted when the machine is rebooted by issuing this command: /sbin/chkconfig httpd on Password protect the admin.example.com interface using http authentication, otherwise anyone will be able to create and delete accounts. The following command will create a superuser called mkdoc1 with the password mkdoc1 (you need to use real versions): htpasswd -bc /var/www/mkdoc/mkdoc-site/.htpasswd mkdoc1 mkdoc1 You should now be able to log-on to your MkDoc site using the initial user account you configured in install.conf and start creating content. Online documentation is available here: http://mkdoc.com/help/ Any further questions regarding MkDoc can be posted to the mkdoc-users mailing list, you can subscribe here: http://lists.webarch.co.uk/mailman/listinfo/mkdoc-users -- 2002-07-12 Bruno Postle