INSTRUCTIONS TO INSTALL FLE3 1.3
================================

More documentation is available at http://fle3.uiah.fi/

This document contains brief instructions to get Fle3 up and running.
If you're upgrading from a previous Fle3 installation, please see
the instructions at the end of this document.

This document assumes you've already installed Python, Zope and
possibly PIL.


DOWNLOAD FLE
------------

	Download the latest archive from

	http://fle3.uiah.fi/download.html

	If you have Debian, get the .deb package and install it:
	"dpkg -i package.deb"

	Otherwise use the .tar.gz or .zip archive. You need to unpack
	the archive, which will produce a new subdirectory FLE. This
	directory should be placed inside the Products folder of Zope.

	Unarchiving the .tar.gz package (change directory as appropriate):

        % cd /usr/local/zope/lib/python/Products/
        % tar zxf fle-x.y.z.tar.gz

	NOTE! If you are upgrading from an earlier version of FLE3,
 	we suggest that you:
	
	 1) take a full backup of your current 
	    /lib/python/Products/Fle directory	
	
	2) More importantly, 
	   remove your old ./lib/python/products/FLE
	   directory before unpacking the new version into your products
	   directory. 

	This procedure is done to avoid conflicts and problems arising
	from file name changes (old files showing in the system in
	addition to the new files that do the same thing).



ADD FLE AS A ZOPE PRODUCT
-------------------------

	What's important here is that FLE is installed inside Zope's
	"Products" folder, inside a folder named "FLE". You can place
	FLE anywhere else if you wish, but you should then make a
	symlink inside the Products folder to the actual location.

	Now restart Zope. You can do that from the management interface
	(http://hostname/manage) using a web browser or with the system
	tools (ie. zopectl).

	After Zope has restarted, it has located the FLE product. In
	the management interface, the Products list inside the Control
	Panel should list FLE and it should not be broken.


CREATE A NEW FLE ENVIRONMENT
----------------------------

	To actually start using Fle, you need to create an instance
	of it, using Zope's management. Using your browser, move to the
	root folder in the management view. From the drop-down box at
	the top right, select "FLE". You will now be presented with
	a form containing details on your Fle3 environment.

	Fill out the form and submit it. You now have a working Fle3
	installation running. Next you'll want to go to Fle3 (just point
	your browser to it) and add new users in User Management.


TROUBLESHOOTING
---------------

Crashing problems with ZOPE (2.5.x), Python and FreeBSD?
 You can try following fix sent by Geoff Fellows:

 Change to Python2.1.2/config.h

 #define PTHREAD_SYSTEM_SCHED_SUPPORTED
 (seems this is not correctly set by configure)


 Add a line to Python2.1.2/Python/thread_pthread.h
 after
        pthread_attr_setscope(&attrs, PTHREAD_SCOPE_SYSTEM);
        pthread_attr_setstacksize(&attrs, (1<<17));

 (sets the thread stack size to 128KB - a bit excessive I think but much
 better than the default 1KB)


UPGRADING FROM A PREVIOUS VERSION OF FLE
----------------------------------------

	If you're using Fle1 or Fle2, there's no upgrade. Fle3 is a
	completely separate product.

	If you're using an older version of Fle3, you can move your
	existing Fle3 instances with their user information and
	knowledge building to the new version.

	For a minor update, follow these steps:
	1. Unpack the archive into the correct folder (remove
	   the previous version)
	2. From ZMI (Zope's Management Interface) inside 
	   Product Management refresh FLE.
	3. Using ZMI, go to FLE's Tools tab and click "Reload everything"
	   (this might take several minutes on a very large database).

	If the program has changed significantly (see list below), you'll
	need to export the data from the previous instances, (re)move
	them, copy the new version over the old one, refresh the product
	and create new instances, importing the data back.

	Exporting can be done by the fle administrator, by pointing the
	browser to http://server/fleinstance/fle_export. You will get
	as a reply a zipped export file, which you should save somewhere.
	Do this for all your FLE instances.

	Next you should remove the existing FLE instances. Remember, Zope
	has an undo feature, so you can restore them if something goes
	wrong. You can also just rename them to something else.

	Now unpack the new version of FLE and replace the old one with it.
	Then refresh the FLE product from Zope's management interface. Next
	create new FLE instances corresponding to the old ones. In each case,
	when filling out the creation form, remember to attach the proper
	zipped export file in the last field. This will reinstate the entire
	Fle instance with all users, knowledge building and so on.

	If exporting fails, you can try to first upgrade the code and then
	do first the export, then rename/delete the instances and import
	the data into new instances. With upgraded code, the UI will break
	so you'll need to export and import pretty quickly so your users
	don't see an error page for too long.


SPECIAL CONSIDERATIONS WHEN UPGRADING TO FLE 1.3
------------------------------------------------

	Old Fle3 environments from previously released versions must
	be exported and then imported after the upgrade to Fle3 1.3.


RUNNING FLE WITH DAEMONTOOLS
----------------------------

	The webserver that comes bundled with Zope is very unstable. It may
	crash under load, and not come back up without explicit actions.
	Daemontools can be used to monitor Zope status, and restart a crashing
	Zope.

	More information about daemontools can be found at
	http://cr.yp.to/daemontools.html.

	You just setup a daemontools service like this:
		% mkdir /service/zope
		% cat <<EOF > /service/zope/run
		#! /bin/sh
		echo starting zope
		exec su -l granbo -c /zope/devel/Zope/start -w 8080 -f -
		EOF
	Then you restart daemontools monitoring process, and zope should
	come up on it's own.


RUNNING FLE WITH APACHE
-----------------------

	When running Apache the character encodings don't work, 
	even though on every page the character encoding is set to utf-8
	with a meta tag. 

	The reason is Apache and its behavior in AddDefaultCharset to set 
	default encoding to ISO-8859-1 if nothing else is set, and it also 
	overwrites whatever is set in the html head section.

	The answer is to set in the VirtualHost section AddDefaultCharset 
	Off, which then preserves the encoding directives set by Zope.

	This instruction was sent by Heimo Laukkanen.
