MapChat 2 Installation Instructions
===================================

This applies to the latest development branch of the code for MapChat 2 (revision 257)

Requirements
============

- PostgreSQL 8.3+
- PostGIS 1.3.x+ (if possible, use beta releases of 1.4.x to avoid crashes while processing some very large geometries)
- PHP MapScript for MapServer 5.4.1 (5.4.0 might work, but recent changes in MapScript in 5.4.1 required some code updates)
- PHP 5.2.x+ (with gd, pgsql, xml, and pdo modules installed/enabled, along with mapscript)
- Apache 2.2.x + mod_rewrite enabled (mod_ssl also recommended for encryption of data transfers)
- One writeable/web-acessible web folder configured in the Apache service (for storing cached map tiles loaded by client browsers)

Introduction
============

This installation procedure assumes that you already have a working environment with the above resources installed.

The software has been developed and tested in various linux environments (Fedora 8/9/10, Debian 5).  It has been designed to be operating system independant (i.e., it should run on any system with the above requirements installed).  However testing on non-Linux systems has not been conducted frequently (though it has been installed on Windows at least once).


Installation Steps
==================

Step 1: Add MapChat2 to Apache configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There is a sample configuration file located in the setup folder of the mapchat2 source code directory.  Copy this to your apache webserver's configuration folder (e.g., /etc/httpd/conf.d in Fedora, /etc/apache2/sites-available in Debian, c:/ms4w/httpd.d in MapServer for Windows), and edit the paths as appropriate to point the html folder in the mapchat2 source code directory, and assign any desired alias.

Step 2: Configure the Apache Rewrite Module for MapChat2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Located in the mapchat2 html folder is a file named .htaccess-dist - copy this file to .htaccess, and edit it so that the baseurl points to the virtual path for your mapchat2 installation (e.g., use '/' if mapchat is access from http://www.example.com/, or '/virtualpath' if it is accessed form http://www.example.com/virtualpath).

If you have want encryption (e.g., for passwords) and if you have SSL properly configured on your webserver, the rest of the file should be left as-is.  Otherwise, to disable automatic redirection, then comment-out the following two lines:

   RewriteCond %{HTTPS} off
   RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [L]

The last line in this file is required for the rest of MapChat2 to run properly, and should not be commented-out:

   RewriteRule !\.(ico|gif|jpg|png)$ index.php

Step 3: Configure the MapChat2 PHP Library
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In the library folder in the mapchat2 source code folder, there is a file name config.php-dist.  Copy this file to config.php, and open it in a text editor.  Review the parameters, and ensure any paths/options are appropriately defined.  The most important things to look for here are:

- $tmpDir: ensure that this points to a writeable folder that temporary data can be saved to.

- $ramDir: this can be used as a substitute for $tmpDir in some situations.  It must also be a writeable folder - if you can create a ramdisk on your server with a folder that can be specified here, then temporary files can be quickly read/written without any I/O on the server's hard disks.

- 'useCookies': set this to true to remove the ?sid=################ that is appended to urls in MapChat (requires browsers to allow cookies of course).

- "debug" and "minify": for debuging, you can set both of these to false, and optimization techniques for on-demand javascript compression and loading will be disabled.  "debug" is also used to determine the verbosity of error messages displayed in the browser.

- 'tmpWeb' and 'tmpWebURL': these must respectively point to the local and web-accessible locations of a folder that will be used for storing map tiles.
*** NOTE: this web folder must already be configured separately, as indicated in the requirements above.

- 'cacheName': this is the folder name that will be used to store map tile caches.  It does not need to exist (it will be automatically created/populated with files inside of the 'tmpWeb' folder).

- 'database': edit the parameters here to reflect your database configuration.  The database named by 'dbname' does not need to exist yet, but if it does, it must contain the mapchat2 schema design.  For the security concious, a non-superuser that would only access the mapchat database should be configured here.

- 'modules': this might need to be modified (e.g., in some cases the libraries do not have 'php_' at the start of their names), but this won't matter if the libraryies are already loaded in the php configuration.


Step 4: Initialize the MapChat2 Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your database does not exist, then you can have the website create it for you.  This ONLY works if you connect to the webserver from the same location (i.e., localhost, or 127.0.0.1).  You will either need direct physical access to the server with a desktop and browser running, or (for linux servers) establish an ssh tunnel and setup a socks proxy in your browser.

Point your browser to http://localhost/pathtomapchat.  If you are connecting from 127.0.0.1, then you will see a list of input boxes asking for the email and password for the default admin user account, passwords for the various default administrative groups.  The bottom section defines the superuser/maintenance database on the PostgreSQL database service that will be used (this can be remotely located, as determined by the database hostname in config.php, but remote superuser access to a database is not recommended).

The last two input boxes must contain the pathnames to the PostgreSQL's contrib folder and to the PostGIS sql install files (lwpostgis.sql and spatial_ref_sys.sql).  These may or may not be in the same folder depending on your system's setup.  These file must be readable by the web server - even if the database is remotely located, there must be access to these files, or at least to a copy of them.

When all of the information is configured, click the setup button.  Any errors should be reported in the browser.  Otherwise, after successful completion, you should be able to point your browser back to the mapchat installation's URL, and login as Admin.


Step 5: Create a Mapfile
~~~~~~~~~~~~~~~~~~~~~~~~

These instructions will not go through the details of creating MapServer mapfiles, as this is documented in detail at http://www.mapserver.org.  However, there are some additional things that are needed to specifically meet the needs of MapChat.

First, it is recommended to have the following outputformats in your mapfile:

	OUTPUTFORMAT # for high-quality vector layers
		NAME 'AGG_PNG24'
		EXTENSION "png"
		MIMETYPE "image/png"
		DRIVER AGG/PNG
		IMAGEMODE RGBA
		TRANSPARENT ON
	END

	OUTPUTFORMAT # for imagery layers - adjust quality below as desired
		NAME 'AGG_JPEG'
		EXTENSION "jpg"
		MIMETYPE "image/jpeg"
		DRIVER AGG/JPEG
		IMAGEMODE RGB
		FORMATOPTION "QUALITY=75"
	END

	OUTPUTFORMAT # recommended for vector layers where low-bandwidth is a must
		NAME 'GD_GIF'
		EXTENSION "gif"
		MIMETYPE "image/gif"
		DRIVER GD/GIF
		IMAGEMODE PC256
	END

	IMAGETYPE "AGG_PNG24"

Next, make sure all of your layers have a GROUP property assigned to them.  Each unique GROUP value represents a separate layer of image tiles that will be rendered in the client browser.  Generally, fewer groups are better, as more image tile layers means more work for the browser.  A good choice might be to put layers into two groups for "RASTER" and "VECTOR" layers.

Finally, there are several required and optional metadata elements that must be added to each layer:

	METADATA
		
		# this group determines the category the layer is listed under (e.g., in the legend control)
		"mapchat_display_group" "Imagery" 
		
		# this doesn't affect anything yet, but the idea is to have layers such as imagery be mutually exclusive within a display group if they are specified with the 'radio' option.
		"mapchat_option_type" "radio"
		
		# This is the outputformat from the MapFile that will be used to render tiles.  The first layer in a GROUP determines this, but it is a good idea to add it to all layers.  To use alpha transparency, use the keyword 'alpha', which defaults to AGG_PNG24 and maintains opacity for superimposed layers of tiles.
		"imageformat" "AGG_JPEG"
		
		# these are tab-separated column names that you want displayed in a mapscript query result for this layer (must be defined if you want to exclude some columns and/or if you want to use column aliases).
		"mapchat_fields" "x  y  value_0  value_1  value_2"
		
		# these are the aliases for the columns listed above
		"mapchat_aliases" "Grid X-Coordinate   Grid Y-Coordinate Red Value   Green Value Blue Value" 
		
	END

The rest of the MapFile can be configured as any MapServer mapfile normally would be.  Be sure to include projection information for the mapfile and the map layers, as well as UNITS, EXTENT.  The SYMBOLSET, and FONTSET can be set to 'etc/fonts.txt' or 'etc/symbols.sym', which will default to the corresponding files located in <mapchat_path>/maps/etc/.  These may be substituted as desired.


Step 6: Create a discussion config XML file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This step is fairly simple, but required.  The default setup includes a default discussion configuration file located at <mapchat_path>/config/demo.xml.  You can use this as-is, but it is a good idea to copy this, and modify it to your own needs.  The following elements are likely to be of interest:

	<scales>: This element should contain a comma-separated list of scales in descending order.  These are the scales at which MapChat will render tiles for the client interface.
	
	<precision>: A positive integer will increase the number of decimal points that certain coordinate data are recorded at (e.g., user drawings, or returning shapes to highlight on the map).  Higher precision means more bandwidth.
	
	<svg_limit>: This is the character-length limit for SVG data (e.g., when highlighting selected/queried shapes).  Shapes that have a larger SVG string than this number will usually be converted to a point with an extent (except for a user editing his/her own drawings)
	
	<user_imageformat>: This is the outputformat that should be used for the USER image tile layer (this image GROUP is added to the mapfile by MapChat if it doesn't already exist).  For high quality images that maintain alpha transparency, use the keyword 'alpha' in this property (like the imageformat metadata element described in Step 5), but remember that using this instead of GD_GIF will require more bandwidth.
	
	<user_opacity>: If you pick 'alpha' for the user_imageformat element, then this value determines the opacity of user-drawn features.

	<menu>: This defines the object used in the default menu.  The <li> tags are interpreted to call JavaScript classes designed for the MapChat environment.  The demo includes all tools created for the MapChat menu, but you might want to exclude the MapChat.Irrigation.Planner tool by removing or commenting-out its <li> tag.
	
	<mapToolBar>: This defines the toolbar buttons that appear in the default Map Tools toolbar (which is one of <menu> items).  You may include/exclude tools if desired here.
	
	<chat>: This currently only includes one option, which is <pollTime> - this determines the number of milliseconds between attempts made by the chat module to get updates from the server.
	

Step 7: Create users/groups/discussions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To create users, point a browser to the url for your MapChat installation, and login as admin.  Links listed under admin options on the right will give you access to control dialogs for creating users, groups and discussions.  User permissions are allocated through their membership to various groups (where group permissions are set).  Adding members is accomplished by clicking the 'Edit Members' button in the Group management dialog (close the members list and click apply after this is done).  The same approach is used to add users and groups as members of discussions.

When creating discussions, you need to specify a mapfile (relative to the maps folder), a config file (relative to the config folder), and an appropriate SRID that exists in the PostGIS spatial_ref_sys table.  Typically this should match the projection setting in your mapfile.  A default extent may be specified as an EWKT-string, although this is not currently used (it will eventually be used as the default extent for when the discussion/map is opened).
