root/trunk/docs/INSTALL.txt

Installation instructions for LeMill
====================================

You need:

 * Plone 2.5.x
 * Zope 2.8-2.9 (as required by your version of Plone)
 * Python 2.4.x (as required by your version of Zope)
 * Kupu 1.4 -> (http://plone.org/products/kupu/releases) 

Installing LeMill for the first time
------------------------------------

1. Install Python, Zope and Plone, by following their respective
   installation instructions. Plone can be obtained as a product
   package for Zope, or as a stand-alone package that contains
   everything. NOTE: If you install Zope so it uses your system's
   default Python environment, installing additional packages (steps 3
   and 4) is easier. If you get a Zope or Plone package that has its
   own Python environment, you'll later need to make sure that you
   install the additional packages into the same Python environment
   that Zope uses.

2. Install newer version of Kupu over Plone's default kupu version. (required for LeMill 3.0 onwards) Download the latest package from http://plone.org/products/kupu/releases and extract it. Remove old Products/kupu -folder and replace it with the new one. 

3. Download the LeMill archive and extract it into the Products/LeMill
   folder of your Zope instance.

4. Make sure the Python Imaging Library (PIL) is installed. You can get it
   from here: http://www.pythonware.com/products/pil/.

5. Enable Captcha-based spam protection in LeMill.
   Different Captcha solutions can be used in LeMill (some of them might
   require changing product code LeMill product code).

   4a. Current solution used is an external reCAPTCHA service.
       Go to your Zope instance zope.conf file (situated in /etc of your
       instance root) and add several lines in order to enable reCAPTCHA 
       functionality:
      
       <product-config lemill>
         recaptcha_public_key PUBLICKEY
         recaptcha_private_key PRIVATEKEY
       </product-config>
      
       Note that PUBLICKEY and PRIVATEKEY should be unique keys that can be
       acquired from http://recaptcha.org.

       NB! As long as you connect to your instance as "localhost", recaptcha 
       won't check that your domain matches that of the keys.

   5b. Install the pycaptcha Python package to enable Captcha-based spam
       protection.  Download the egg from
       http://pypi.python.org/pypi/PyCAPTCHA/0.4 (for Python 2.4) and
       install it as you would any Python egg file (instructions on
       installing eggs can be found by searching the net for "python egg
       installation", but usually the easiest way is to first install the
       Python setuptools, which provides you with the easy_install utility
       that can install eggs.

       NB! Note that the pyCaptcha package has an unfortunate conflict
           with Zope. pyCaptcha tries to import the Image class from
           Python Imaging by saying "import Image". The problem is that
           under Zope this class will result in Zope's own Image class. So
           all cases of "import Image" need to be changed to "from PIL
           import Image". pyCaptcha will then work with and without Zope.

6. Sign up for Google Maps API key from http://code.google.com/apis/maps/signup.html 
   and add it to your Zope instance zope.conf file into <product-config lemill> tag:
   
   google_maps_api_key APIKEY

7. Start Zope.

8. Using your browser go to the ZMI (Zope Management Interface), which
   usually is something like http://localhost:8080/manage. On the main
   window, open the drop-down menu on the right and select "Plone
   Site" to create a new Plone environment. In the following form you
   will choose the id for the environment (which becomes part of the
   path). You must also select from the "Extension Profiles" box the
   profile "LeMill" so that instead of a normal Plone site you get a
   LeMill site.

9. After this you should be able to access your LeMill by going to
   http://localhost:8080/id (where "id" is the id you chose when
   creating the environment).

10. If you plan on running a production system, we suggest the
   following additional operations:

   * Run a separate ZEO server and connect your Zope to that, so you
     can easily add servers and make a cluster if necessary.

   * Run Apache2, Squid, Varnish or some other proxying web server in
     front of Zope, so you can employ efficient caching techniques.

   * Take a look at Plone product "CacheFU" to help in tuning the
     caching parameters and improve performance.

11. (Optional) If you want to generate mathematical formulas without
   depending on an external web service, you'll need to install a
   working LaTeX environment into the same server, and you also need
   to install the LocalFS Zope product into your Zope environment.

12. (Optional) If you want to generate PDF files from collections,
   you will need to install additional component to the python
   being used by your instance. You can download the latest version
   of PISA from http://pypi.python.org/pypi/pisa/. You should install 
   all the dependencies that PISA requires to be fully functional. 
   You can download suitable ReportLab Toolkit version from 
   http://www.reportlab.org/downloads.html

Upgrading from older versions
-----------------------------

There are several steps, of which not all are always necessary, but
unless you're sure about what's needed or not, run all of them.

Also see the utility script "upgrade_lemill.py" in this folder, which
can automate the upgrade process for you (just edit the configuration
items at the beginning and run it).

But here's basically what's needed:

 * Install the new version, replacing the old one, in Products/LeMill

 * Restart Zope

 * Go to ZMI (Zope Management Interface), navigate to your LeMill instance, and

   * In portal_quickinstaller reinstall LeMill
   * In portal_migration go to Setup and update the "LeMill site" customization policy
   * In portal_workflow run "Update security settings"
   * In archetypes tool run "Update schema"
   * In portal_catalog run "Update catalog"

   These steps aren't always necessary except during major upgrades,
   and they are often run automatically when you do the first of these
   steps, but it doesn't hurt to make sure.

   If one of the steps fails, then try the other ones first, and retry
   the failed steps later. Sometimes there are complex
   interdependencies which are solved when running the steps in a
   certain order. All of the steps are completely safe, you can call
   them as many times as you want. They will only make changes if
   there are changes to be made, and will not break the system.

   And of course you can do all of this with the accompanied
   upgrade_lemill.py script (although you might need to run it a few
   times to get all steps executed without errors).


Help and support
----------------

You might get help from the IRC channel #lemill in the Freenode
network. If you don't have an IRC client, you can go to
http://lemill.net/community/ and click on the "Join LeMill chat..."
button to enter the IRC channel through your web browser.