Upgrade from 1.4 to 1.6

MKDoc-1.6 technology provides a number of new features, these features involve some changes in the database schema, the system environment (libraries such as perl), the MKDoc software itself and the HTML templating system.

Upgrading the database is simple, see the instructions below.

MKDoc-1.6 requires some changes to the server itself, the most significant is that MKDoc is a mod_perl application and the new version requires an upgraded perl-5.8 for improved UTF-8 support. An important consideration if you intend a seamless upgrade on one server, is that MKDoc-1.4 requires perl-5.6 and will not work with the newer perl-5.8.

With care, the new MKDoc-1.6 software can be installed alongside the existing 1.4 software, indeed both the old and the new software can serve the same data simultaneously with some limitations — Probably you don't want to do this, the simplest way to upgrade is to configure MKDoc-1.6 on a different server and transfer the data.

The templating system now uses the superior Petal TAL specification for WYSIWYG compatible editing throughout — This means that any existing modifications to templates and CSS style sheets will need to be reworked for the new system.

Database compatibility

All MKDoc data (apart from attached files and images) is stored in a single MySQL database. For MKDoc-1.6, there have been some minor changes to the database schema to add new features; a running 1.4 database can be upgraded to this new schema at any time without problems even if the software never gets upgraded to 1.6.

Upgrading the database

Backup your database to a file using the unix shell:

mysqldump -umyusername -pmypassword mydatabase > mydatabase-backup.sql

Download this upgrade script:

Run the SQL script to upgrade the database schema, it doesn't matter if this command is run multiple times:

mysql -umyusername -pmypassword mydatabase < upgrade-14-16.sql

Test your MKDoc-1.4 site to see if the changes were applied successfully; if not, you can restore the original database from your backup file.

This process activates the ‘admin’ user and gives it a password ‘changemenow’. You should log-in to the superuser interface and change the password for the ‘admin’ user — In future this password will be used for all site-wide administration tasks.

Software installation

This guide is going to assume that you are installing the new MKDoc-1.6 software on a separate server from your existing MKDoc-1.4 sites. The base perl system requirements are different for the two versions of software, so installing both the old and new software on the same server involves having two co-existing versions of perl — Setting-up such a system is beyond this guide.

Follow the installation instructions as set-out in the INSTALL.TXT file distributed with MKDoc-1.6. We recommend creating an initial test site to verify that everything is ok.

Migrating the site

Assuming that the database containing your existing content is already available; run the site installation procedure and enter the existing database connection parameters alongside the other parameters — When you finish, the installation program will ask if you want to keep the existing data or erase it and start again.

Transferring the remaining data

MKDoc stores the content of pages in the SQL database where it can be easily indexed and searched, but attached items such as images, photos and files are stored on the filesystem as normal files.

All this attached data can be found in the static folder in your $SITE_DIR. You need to copy the contents of your old static folder into the static folder of your replacement MKDoc-1.6 site.

Finishing off

Test the new site, everything should be exactly the same as before except with the default plain MKDoc templates.

IMPORTANT, if you are sharing a database with a live MKDoc-1.4 site you can browse the new editor/users interface, but you must not edit anything or submit any changes to any documents — This will make those documents incompatible with the live MKDoc-1.4 site.

Troubleshooting errors

If you see Internal Server Errors in your web-browser, look at the apache error-log for detailed explanations — Possible causes are:

• Missing templates — If any of the documents in your existing database use custom templates with non-standard names, these templates will need to be recreated for the new site.

• Missing or incomplete perl modules — The error log will give some indication of the missing modules.

Styling your site

The new site will have the plain default look and feel, you probably want to customise this.

Customising your look-and-feel is documented elsewhere, but these are the steps you might like to take (in order of difficulty):

1. Upload some modified CSS via the web interface (CSS Cascading Style Sheets are a standard way of modifying the look and feel of a web-page without changing any HTML) — Any file named style.css uploaded to the homepage of your site will be applied as CSS to every document on the site. CSS can be used to modify the page layout, colours and fonts — Everything except the ordering of elements in a page.

2. Replace the existing CSS on the filesystem — This will involve editing the $SITE_DIR/httpd/httpd.conf file and pointing the /.static/css Alias to the new location. Do this if you want to replace the existing CSS entirely rather than just override part of it.

3. Modify the Petal templates (TAL Tagged Attribute Language is a widely used XML templating standard), any templates you place in the templates folder will override the default MKDoc-1.6 templates automatically. Do this if you must rearrange the display order of page elements or create new templates for special purposes.