maki manual: Installation

maki: Installation

Requirements

Before installing maki you will need to have several other programs/libraries already installed. In the list below, I mention some version numbers. If the current version is newer, it should probably work. If you experience problems and are using an older version, try upgrading. If you experience problems and are using a newer version, let me know and I'll try to help.

maki was developed on Linux, but should work on any modern platform where you can successfully run Python, PyXML, at least one of the XSL transformers (libxml2/libxslt, Sablotron/Sab-python, 4XSLT (the version from 4Suite), or Xalan/Pyana) and one of the packages that provides a persistent Python interpreter for your webserver (FastCGI, Webware, or mod_python).

Prerequisite Software

software	version	url	required?
Python	2.2 (2.0 and 2.1 should also work)	http://www.python.org/	required
PyXML	0.7.1	http://pyxml.sourceforge.net/	required
mod_python	2.7.6	http://www.modpython.org/	optional
FastCGI	depends on your webserver	http://www.fastcgi.com/	optional
fcgi.py	doesn't have one	http://alldunn.com/python/fcgi.py	optional
Webware	0.7	http://webware.sourceforge.net/	optional
4Suite	0.12	http://4suite.org/	optional
Sablotron	0.82	http://www.gingerall.com/	optional
Sab-pyth	0.52	http://www.ubka.uni-karlsruhe.de/~guenter/Sab-pyth/	optional
libxslt	1.0.18 (requires libxml2 2.4.22)	http://xmlsoft.org/XSLT/	optional
libxsltmod	1.3a	http://www.rexx.com/~dkuhlman/	optional
Xalan C++	1.1 (requires Xerces C++ 1.4)	http://xml.apache.org/	optional
Pyana	0.4.5	http://pyana.sourceforge.net/	optional

General Instructions

Note: At some point I should figure out how to use distutils. For now, the installation is done with a Python script named "INSTALL.py". These instructions have a pretty strong Unix bias. I'll try to add some more Windows-friendly instructions in the future.

After making sure all required software is installed, extract the maki archive file.

tar xvfz maki-VERSION.tgz

Change directory to the newly created directory.

cd maki-VERSION

Edit the file INSTALL.py. Make sure that the values at the top of the file are satisfactory. MAKI_DIR is the path where various maki-related files (including the configuration file, some example logicsheets, a log file, and the cache directory) will live. DOC_DIR is the directory where examples and the manual (in XML format) will be placed. WEB_USER is the username that your webserver (or appserver in the case of Webware) runs as. MODULE_DIR is the path where you want the Python modules to be installed. It must be a directory in your Python search path. If you leave it set to None, INSTALL.py will try to figure out an appropriate value for you. It is probably best to leave this set to None, unless you find that the script tells you that it can't figure out a value.

After exiting the editor, become root and execute the INSTALL.py script.

su python INSTALL.py

What you do next depends on the the webserver/appserver you're using.

Apache/mod_python Instructions

Open the Apache configuration file in a text editor. At some point in the main body of the file add the following lines:

AddHandler python-program .py PythonHandler spb.mod_pythonMakiHandler Action maki /maki.py

If you want maki to handle all requests for .xml files, also add this line:

AddHandler maki .xml

Otherwise, you will at least want to make sure that maki handles the .xml files in the DOC_DIR. Add the following to the Apache config file (replacing DOC_DIR with the actual path you set in INSTALL.py):

<Directory DOC_DIR> AddHandler maki .xml </Directory>

Now restart Apache as you normally do, then skip to the section below titled "Trying it out".

TIP: If the Action directive doesn't work, you will need to enable mod_actions. Consult the Apache documentation for assistance.

Apache/FastCGI Instructions

Make sure you've got mod_fastcgi and fcgi.py installed. Then copy fastcgiMakiResponder.py (from the maki distribution) to somewhere on your system that your webserver can read. For the purposes of these instructions, let's say you copy it to /usr/local/maki/scripts. Next, make sure that the path to your Python executable at the top of fastcgiMakiResponder.py is correct, and make sure that the file is executable.

Then open the Apache configuration file in a text editor. At some point in the main body of the file add the following lines:

ScriptAlias /maki-fcgi/ "/usr/local/maki/scripts/" FastCgiServer /usr/local/maki/scripts/fastcgiMakiResponder.py <Directory /usr/local/maki/scripts> AddHandler fastcgi-script .py </Directory> Action maki /maki-fcgi/fastcgiMakiResponder.py

If you want maki to handle all requests for .xml files, also add this line:

AddHandler maki .xml

<Directory DOC_DIR> AddHandler maki .xml </Directory>

Now restart Apache as you normally do, then skip to the section below titled "Trying it out".

TIP: If the Action directive doesn't work, you will need to enable mod_actions. Consult the Apache documentation for assistance.

Webware/WebKit Instructions

Copy the directory "webware_plugin/maki" (from the maki distribution) to some directory where WebKit recognizes plugins. By default, this would be your main Webware directory, but it is possible to add other directories to the plugin search path by editing Webware/WebKit/Configs/AppServer.config and modifying PlugInDirs. Assuming you're on Unix, you are currently in the maki distribution directory, and want to copy webware_plugin to /usr/local/Webware, the command would be:

cp -R webware_plugin/maki /usr/local/Webware

Now edit Webware/WebKit/Configs/Application.config and add a context for your maki DOC_DIR. For example:

'Contexts': { 'maki': 'DOC_DIR', # add this line 'Admin': '%(WebKitPath)s/Admin', 'Examples': '%(WebKitPath)s/Examples', 'Docs': '%(WebKitPath)s/Docs', 'Testing': '%(WebKitPath)s/Testing', 'default': '%(WebKitPath)s/Examples', },

(Of course, you will want to replace the string DOC_DIR with the actual path you set in INSTALL.py.)

If you want WebKit to do its extension magic for .xml files, add '.xml' to the list of 'ExtensionsToServe'. For example:

'ExtensionsToServe': ['.xml','.py','.psp','.html'],

(This isn't necessary to run maki. It simply allows you to hide the .xml extension in your urls.)

Now restart the WebKit AppServer as you normally do, then skip to the section below titled "Trying it out".

TIP: If you're using the CGI adapter on Windows, instead of building a standalone .exe version of WebKit.cgi (as the WebKit installation guide suggests) I would recommend getting a copy of wkcgi.exe from http://webware.sourceforge.net/MiscDownloads/ForCVS/Windows/ and copying it into your cgi-bin or scripts directory.

Trying it out

Try hitting the "index.xml" file in the DOC_DIR. The url is probably something like this for mod_python or FastCGI:

http://127.0.0.1/maki/index.xml

or like one of these for Webware/Webkit:

http://127.0.0.1/WK/maki/index.xml http://127.0.0.1/webkit.cgi/maki/index.xml http://127.0.0.1/scripts/wkcgi.exe/maki/index.xml

If you can hit this page successfully, you got maki working. The page has a link to the manual and several examples for you to study.

Otherwise, you may want to double-check your installation and take a look at your webserver's error log and maki's log (MAKI_DIR/maki.log). If you find a problem with my instructions or installation procedure, let me know.