Installation

The installation involves the following steps:

• 0. Prerequisites
• 1. Installing Python libraries
• 2. Compiling
  • Statically linking mod_python into Apache.
  • Compiling mod_python as a DSO
• 3. Testing
• 4. Troubleshooting

0. Prerequisites

• Python 1.5.2
• Apache 1.3

You will need to have the include files for both Apache and Python, as well as the Python library installed on your system. If you installed Python and Apache from source, then you have nothing to worry about. However, if you are using prepackaged software (e.g. Linux Red Hat RPM, Debian, or Solaris packages from sunsite, etc) then chances are, you just have the binaries and not the sources on your system. Often, the include files and the libraries are part of separate "development" package. If you are not sure if you have all the necessary files, either compile and install Python and Apache from source, or refer to the documentation for your system on how to get the development packages.

1. Installing Python Libraries

• Unzip and untar the distribution file into some directory (xxx is the version number):

      $ gunzip mod_python-xxx.tgz
      $ tar xzvf mod_python-xxx.tar
  	  

• Copy the directory lib/python/mod_python to some place in your PYTHONPATH, usually /usr/local/lib/python1.5/site-python (this step will require root access):

        $ su
        # cp -r mod_python-xxx/lib/python/mod_python /usr/local/lib/python-1.5/site-packages/
  	  

• Compile the modules in the mod_python package (still as root):

        # python /usr/local/lib/python1.5/compileall.py /usr/local/lib/python1.5/site-packages/mod_python
  	  

2. Compiling

There are two ways that this module can be compiled and linked to Apache - statically, or as a Dynamic Shared Object.

Static linking is a more "traditional" approach, and most programmers prefer it for its simplicity. The drawback is that it entails recompiling Apache, which some people cannot do for a variety of reasons. For example in a shared web hosting environment the Apache binary might not be writable by the user.

Dynamic Shared Object (DSO) is a newer and still somewhat experimental approach. The module gets compiled as a library that is dynamically loaded by the server at run time. A more detailed description of the Apache DSO mechanism is available here.

The advantage is that a module can be installed without recompiling Apache and used as needed. DSO has its disadvantages, however. Compiling a module like mod_python into a DSO can be a complicated process because Python, depending on configuration, may rely on a number of other libraries, and you need to make sure that the DSO is statically linked against each of them.

Statically linking mod_python into Apache.

• Copy src/mod_python.c from the distribution you just untarred into the Apache source tree under src/modules/extra:
  (assuming Apache sources are in apache_1.3.12)

      $ cp mod_python-xxx/src/mod_python.c apache_1.3.12/src/modules/extra/
  	  

• A this point you have two choices, two ways to build Apache - the new "Apaci" or the old "Configure". Use Apaci if you don't know the difference:
  
  EITHER (Apaci)
  • Run ./configure from Apache directory telling it to activate the Python module, then make to compile Apache:

         $ cd apache_1.3.12
         $ ./configure --activate-module=src/modules/extra/mod_python.c
         $ make
    	      

  OR (Configure)
  • Cd into the src directory, edit the Configuration file to add the module, run Configure, then make to compile Apache:

         $ cd apache_1.3.12/src
         $ vi Configuration
           [add a line "AddModule modules/extra/mod_python.c"]
         $ ./Configure
         $ make
    	      

• Now either run "make install" to install Apache for the first time, or (more likely) simply copy over the new httpd binary to wherever Apache is on your system. This step will probably require root. E.g.:

        $ su
        # cp src/httpd /usr/local/apache/bin/httpd
  	  

• Finally start (or restart) Apache. This is typically done like this:

        # /usr/local/apache/bin/apachectl stop
        # /usr/local/apache/bin/apachectl start
  	  

• If Apache didn't start, refer to the Troubleshooting section below.

Compiling mod_python as a DSO.

The DSO compilation should be a simple process involving the apxs tool included with Apache, but due to differences in the dynamic linking mechanism and other subtleties, the procedure varies from system to system. Below are some notes on the successful installations I've been able to perform on systems I have access to. The future plan is to improve this procedure and hopefully come up with a simple script that will compile a DSO on your system. Until then, however, these notes is all I have:

    On Linux, I was able to get dso to work the following way:

    [Linux 2.2.14, Debian potato, gcc 2.9.52, Apache 1.3.12,
     standard Debian Python development package installed]

    1. cd src/modules/extra
    2. axps -I /usr/local/include/python1.5 -c mod_python.c \
            /usr/local/lib/python1.5/config/libpython1.5.a -lpthread
      (You don't nead -lpthread if your Python is compiled without threads)


    On FreeBSD 4.0 STABLE (May 14 2000), the Python port from the ports
    collection is compiled with threads, but Apache is not. On FreeBSD, bjects 
    linked with thread support are linked against a different version of libc - 
    libc_r, and I do not think you can mix the two. The best solution is to
    quickly download and compile Python and link against that:

    1. tar xzvf py152.tgz
    2. cd Python-1.5.2
    3. ./configure
    4. make
    5. now cd to the mod_python directory 
    6. cd src/modules/extra
    7. apxs -I ~/src/Python-1.5.2/Include -I ~/src/Python-1.5.2 \
       -c mod_python.c ~/src/Python-1.5.2/libpython1.5.a -lm


    On Solaris 2.7 (SPARC), egcs-2.91.66. Again, I wasn't able to get it to
    work with threads, so just like with FreeBSD (above) the easiest thing is
    to quickly compile Python. The apxs command is then the same as for FreeBSD. 

    If, upon starting Apache, you get an error mentioning the unresolved 
    __eprintf symbol, do this:

    1. Find where your libgcc is (try "locate libgcc"). Mine was in 
      /usr/local/lib/gcc-lib/sparc-sun-solaris2.7/egcs-2.91.66/libgcc.a

    2. Extract the object, containing the __eprintf using ar:
       ar -x /usr/local/lib/gcc-lib/sparc-sun-solaris2.7/egcs-2.91.66/libgcc.a \
      _eprintf.o

    3. Now run apxs, but add _eprintf.o as the last argument. This will link the
       object in and should solve the problem. 
      

3. Testing

• If you compiled mod_python as a DSO, you will need to tell Apache to load the module by adding the following line in the Apache configuration file, usually called httpd.conf or apache.conf (assuming you placed mod_python.so in the libexec directory in the ServerRoot) :

        LoadModule python_module libexec/mod_python.so
  	  

• If your Apache configuration uses ClearModuleList directive, you will need to add mod_python to the module list in the Apache configuration file:

        AddModule mod_python.c

• Make some directory that would be visible on your website, for example, htdocs/test.
• Add the following Apache directives, which can appear in either the main server configuration file, or .htaccess. If you are going to be using the .htaccess file, make sure the AllowOverride directive applicable to this directory has at least FileInfo specified. The default is None, which will not work.

        AddHandler python-program .py
        PythonHandler test
        PythonDebug 

• At this time, if you made changes to the main configuration file, you will need to restart Apache in order for the changes to take effect.
• Edit test.py file in the htdocs/test directory so that is has the following lines:

        from mod_python import apache
  
        def handler(req):
            req.send_http_header()
            req.write("Hello World!")
            return apache.OK 

• Point your browser to the URL referring to the test.py, you should see "Hellow World!". If you didn't - refer to the troubleshooting step next.

4. Troubleshooting

There are a couple things you can try to identify the problem:

• Carefully study the error output, if any.
• Check the error_log file, it may contain useful clues.
• Try running Apache from the command line with an -X argument:

        ./httpd -X

  This prevents it from backgrounding itself and may provide some useful information.
• Ask on the mod_python list. Make sure to provide specifics such as:
  . Your operating system type, name and version.
  . Your Python version, and any unusual compilation options.
  . Your Apache version.
  . Relevant parts of the Apache config, .htaccess.
  . Relevant parts of the Python code.