FotoBuzz Distribution
2Entwine, LLC
Homepage: http://fotobuzz.org/

Revision History
-------------------------------------------------------------------------
0.1   2004-11-19 Initial release.


Incorporating FotoBuzz in pre-existing webpages
-------------------------------------------------------------------------
After following the instructions below to install the FotoBuzz scripts,
and verifying that the demo page loads successfully, the next step
would be to look at http://fotobuzz.org/howto.html for instructions
on how to use FotoBuzz in pre-existing pages.


PHP installation instructions
-------------------------------------------------------------------------
Requires: PHP 4.3.x or higher
Requires: PHP Expat support

Quick instructions:
Place all of the files in the FotoBuzz distribution in a web accessible
directory. Point your browser at the directory, and the sample page
should be shown with the annotated picture.

Detailed instructions:

1) Create a directory in your webspace for the FotoBuzz files.

2) Copy over the required files:
   [ Macromedia Flash SWF files ]
   fbloader.swf
   fotobuzz.swf

   [JavaScript files]
   fbIR.js   

   [ PHP files ]
   fotobuzz.php
   atomparser.inc
   fbjfif.inc
   fotobuzzxml.inc
   utility.inc
  
3) Copy over demo files:
   index.html
   harbor.jpg

4) Make sure that the demo page renders properly, that annotations
   are viewable, and that annotations are editable.

5) Change user configuration options in fotobuzz.php for added 
   restrictions and security.

6) Review the "Security Considerations" section of this document.

7) See "Configure FotoBuzz for Restricted User Mode" below if only a 
   small number of people are allowed to annotate pictures.

Python installation instructions
-------------------------------------------------------------------------
Requires:  Python 2.3
Requires:  Universal Feed Parser <http://feedparser.org>
Requires:  ElementTree           <http://effbot.org/downloads/#elementtree>
Recommend: mod_python 3.1        <http://modpython.org>

1) Create a directory in your webspace for the FotoBuzz files.

2) Copy over the required files:
   [ Macromedia Flash SWF files ]
   fbloader.swf
   fotobuzz.swf

   [JavaScript files]   
   fbIR.js   

   [ PHP files ]
   fotobuzz.py
   fotobuzzlib.py
   xmlutils.py
  
3) Copy over demo files:
   index.html
   harbor.jpg

4) By default the index.html page makes use of the PHP script. Change
   the single occurrence of fotobuzz.php to fotobuzz.py in index.html.

5) Mod_Python only: Apache requires that an entry be created for
   Python handlers in httpd.conf. The minimum entry would be the
   following:

<Directory "C:/Program Files/Apache Group/Apache2/htdocs/fotobuzz">
	AddHandler python-program .py
	PythonHandler fotobuzz
</Directory>

6) Make sure that the demo page renders properly, that annotations
   are viewable, and that annotations are editable.

7) Change user configuration options in fotobuzz.php for added 
   restrictions and security.

8) Review the "Security Considerations" section of this document.

9) See "Configure FotoBuzz for Restricted User Mode" below if only a 
   small number of people are allowed to annotate pictures.


Configure FotoBuzz for Restricted User Mode
-------------------------------------------------------------------------

Restricted user mode would be where only a restricted set of people are
allowed to annotate pictures, but any number of people would be allowed
to view the annotations. 

The easiest way to do this is by having two copies of the fotobuzz.php
or fotobuzz.py scripts. 

The first copy should be in a directory restricted by using .htaccess or 
some other authentication method. The script in this directory will be 
allowed to write to JPEGs.

The second copy should be in the directory viewable to the intended
audience. That copy of the script should only be allowed to view 
annotations, not write them.

Here's a sample directory layout:

Files                        Configuration option inside of script
---------------------------  -------------------------------------
htdocs \
   fotobuzz_restricted \
       .htaccess
       index.html
       fotobuzz.php          [ $ALLOW_NEW_ANNOTATIONS = True; ]
       ...

   fotobuzz_readonly \
       index.html
       fotobuzz.php          [ $ALLOW_NEW_ANNOTATIONS = False; ]
       ...       

Notes:

1) The index.html files in the respective directories should refer to 
   the FotoBuzz scripts in the same directory.
2) index.html refers to fbIR.js and the two SWF files. Make sure those 
   references are correct.
3) fotobuzz.php depends on .inc files. If they're not located in the
   same directory as fotobuzz.php, then they have to be at least in
   the PHP include path. The simplest solution would be to have copies
   of the .inc scripts in both directories.


Security Considerations
-------------------------------------------------------------------------

The FotoBuzz Python and PHP scripts read and write to JPEG files on
the webserver. Since the scripts have access to portions of the
filesystem, it would be wise to limit the scripts to reading and writing
images only below a certain directory by defining a path using the 
IMAGES_ROOT parameter.

Both the Python and PHP scripts attempt to avoid race conditions when
writing to a JPEG. However, if a race condition occurs, more than one
person could be re-writing the JPEG causing it to become corrupted like a
Rhode Island politician. Given that, it's probably not recommended to let 
the scripts modify JPEGs for which there's only a single copy. Backups are 
recommended.