RAPC Administration Guide

	Caution
	While it might be possible to install the RAPC server on other Windows flavors, only Windows 2003 Server and Windows XP are recommended. The filesystem of c: must be NTFS and not FAT.

Windows 2000 installations have been tested and should work. Windows NT, 95, 98 are ME not recommended.

Installation of RAPC on other operating systems such as Linux may require minor changes to the source code. Please contact the RAPC developers if you are having problems. The initial RAPC version was created on Windows.

At least PostGIS 1.0.3 (lwpostgis.sql) is required to run RAPC without adjustments to the source code.

It is recommended to use at least PostGIS 1.0.3 or higher.

GNU gettext is a widely used system for translation management.

RAPC is using the PHP gettext extension, the translations are edited in the locale/*/LC_MESSAGES/rapc.po files. Replace "*" with a two letter ("ar") or five letter ("ar_JO") language code.

In order to be used by gettext, the source files (rapc.po) files have to be compiled to rapc.mo files.

Editing and compilation is conveniently done with poEdit (Section 4.5.3, “poEdit”). poEdit is also capable of extracting the translation terms from PHP sources.

Messages that have to be translated but are not included in the PHP sources should be added to include/i18n.php. This is the case e.g. for coded values from the database.

Messages residing in the PostgreSQL database should be internationalized using the dcmmstranslation().

The dcmmstranslation() function looks up translations from the Translation table.

The name field of the AdministrativeArea, Landmark and Village should contain the name in the primary language that is used to operate the application. E.g. in the case of landmarks, this is the field that is filled and used if no other translation is given. Additional translations are stored in the translation table.

The shapefile loader (Section 6.1.1, “Shapefile Loader”) allows to update the translation table from fields like name (English), arname (Arabic), etc.

To use translations, e.g. in map files, use the following statement:

dcmmstranslation('en', name)

If no matching translation is found in the translation table, the term to translate is returned by dcmmstranslation().

	Tip
	If you are running Skype, you may want to shutdown Skype while you are installing Apache as Skype might otherwise prevent Apache from using port 80.

	Tip
	If the Apache installation is not fully successful because another program (e.g. IIS) is already using port 80, simply edit httpd.conf to use another port (e.g. "Listen 81" instead of "Listen 80" and run the Apache setup again. Choosing the repair option will complete the Apache installation.

Run the Apache installer. The Apache installer is available from the setup folder of the RAPC CD or from the Apache website: http://httpd.apache.org.

Figure 9. Apache Wizard

Figure 10. Apache License

Figure 11. Apache Readme

Figure 12. Apache Information

Figure 13. Apache Setup Type

Figure 14. Apache Location

	Tip
	The RAPC installer reads the Apache installation folder from the Windows registry. You can install Apache to different locations.

Figure 15. Apache Install

	Tip
	If the Apache installation fails because another application is using port 80, you can use the following commands to find out which application is using port 80: netstat -aon tasklist Look for the process id (PID) of the process occupying port 80 and find the application of the process id.

Run the DCMMS Scripting installer. The installer is available from the setup folder of the CD or from the DCMMS website: http://dcmms.sourceforge.net.

Figure 16. PHP License

Figure 17. PHP Components

	Tip
	PEAR modules can be easily installed and upgraded over the internet. See the PEAR documentation for details. However, the DCMMS scripting installer provides all necessary packages.

Figure 18. PHP Location

This section describes how to install PostgreSQL for Windows.

The PostgreSQL installer (postgresql-8.0.msi) is available from the setup folder of the RAPC CD or from http://pgfoundry.org/projects/pginstaller/.

	Note
	Don't get confused by the two PostgreSQL installer files. They are both required and can only be installed together.

Run the PostgreSQL installer and select the English language.

Figure 19. PostgreSQL Language Selection

Figure 20. PostgreSQL Setup

Figure 21. Installation Notes

Figure 22. Choose Installation Options

	Caution
	Click on the icon next to "PostGIS Spatial Extensions" and select Will be installed on local hard drive.

	Tip
	Instead of installing PostGIS with the PostgreSQL installer, you should install a newer version from a separate installer (at least version 1.0.3). Such an installer is available from http://www.webbased.co.uk/mca/ or from the setup folder of the RAPC CD. Once PostgreSQL 8.1 is released, the PostGIS version included in the PostgreSQL installer will be sufficient.

Note that the PostgreSQL installation path is not important. Please accept the default installation path provided by the installer.

Accept the other settings as shown in Figure 22, “Choose Installation Options” and click Next >.

Figure 23. Service Configuration

Figure 24. Account Error

Figure 25. Password

	Tip
	You don't have to remember the random password. It is only used internally to run the PostgreSQL service on Windows. See Section 3, “Concepts” for detailed information.

Figure 26. Successfully granted the 'Logon as a service' right

Figure 27. Initialise Database Cluster

	Caution
	You'll need this password (for the PostgreSQL superuser "postgres") later on during the installation process e.g. while running the RAPC setup and for database maintenance purposes. Make sure that you remember it well.

Figure 28. Enable Procedural Languages

Figure 29. Enable Contrib Modules

Accept the default selection as shown in Figure 29, “Enable Contrib Modules” and click Next >.

Figure 30. Enable PostGIS

PostGIS will be enabled for the rapc database by the RAPC installer.

Figure 31. Ready to Install

Figure 32. Installation complete

	Tip
	As mentioned in Figure 32, “Installation complete”, it is recommended to subscribe to the pgsql-announce mailing list to stay up-to-date with the latest PostgreSQL developments.

Once the PostgreSQL setup has finished, start the PostGIS setup which is available in the setup folder of the CD or on the internet: http://www.webbased.co.uk/mca/.

Figure 33. PostGIS License

Figure 34. PostGIS Components

	Caution
	Uncheck the option Create Database as shown in Figure 34, “PostGIS Components” and click Next >. The rapc database will be created by the RAPC installer.

Figure 35. PostGIS Location

	Note
	The destination folder is your PostgreSQL installation folder and might differ from the one shown in Figure 35, “PostGIS Location”

Figure 36. PostGIS Database Connection

Figure 37. Installation Complete

Start the RAPC Setup, which is available from the setup folder of the RAPC CD .

Figure 38. RAPC License

Figure 39. RAPC Components

Figure 40. RAPC Location

Figure 41. RAPC Database Connection

You should now be able to start the RAPC from the Start Menu or through the shortcut on the Desktop. Note that the full functionality will only be available once you've completed the data set, e.g. by loading the sample data.

	Note
	The installer will not overwrite existing RAPC configuration files.

The PostgreSQL database is available from http://www.postgresql.org.

The PostgreSQL installation should support UNICODE.

	Warning
	You may run into problems if you use a binary PostgreSQL distribution under Linux or UNIX. In order to use PostGIS and specifically GEOS from PostgreSQL, the binaries have to be linked against libstc++. The PostGIS documentation contains details regarding this issue.

In order to enforce RAPC logins with password authentication, the pg_hba.conf configuration file should be altered like in the following example:

# TYPE  DATABASE    USER      IP-ADDRESS  IP-MASK           METHOD
host    all         postgres  127.0.0.1   255.255.255.255   trust
host    rapc       all       127.0.0.1   255.255.255.255   password

Note that this still allows the PostgreSQL superuser postgres to connect to PostgreSQL server without authentication. However the user postgres is not allowed to log on to RAPC.

Note

The instructions below assume that the PostgreSQL administrator is named postgres and that the postmaster is running on the local machine (localhost). If this is not the case for you, you'll have to adjust the commands accordingly. The same applies to the connection method - if your postmaster is not configured to accept TCP/IP connections, you have to adjust the commands (and possibly the RAPC configuration).

Create a new database named rapc using UNICODE, load the PL/SQL language to the database:

createdb -U postgres -h localhost --encoding=UNICODE rapc
createlang -U postgres -h localhost plpgsql rapc 
           

If PL/SQL was created in template1, the second command will fail. Ignore the error message in this case.

PostGIS is available from http://postgis.refractions.net .

Follow the installation instructions in the PostGIS documentation.

Once PostGIS is installed, change to the directory containing postgis.sql and spatial_ref_sys.sql and load PostGIS to the rapc database:

psql -U postgres -h localhost -f postgis.sql rapc
psql -U postgres -h localhost -f spatial_ref_sys.sql rapc

PostArabic is a small module that adds Arabic shaping functionality to PostgreSQL.

	Tip
	The PostArabic installation is only required in order to display Arabic map labels. If you are not interested in Arabic map labels, you can skip the PostArabic installation.

Follow the installation instructions in the file README.arabic.

Change to the directory containing arabic.sql and load PostArabic to the rapc database:

psql -U postgres -h localhost -f arabic.sql rapc

The Apache webserver is available from http://httpd.apache.org .

Follow the installation instructions in the Apache documentation.

Apache is configured through the httpd.conf file. In order to access the RAPC application by a convenient URL like http://localhost/rapc/, you should add lines like the following to httpd.conf:

Alias /rapc "c:/program files/rapc/"
<Directory "c:/program files/rapc">
  Options Indexes Multiviews
</Directory>

Alias /ms_tmp/ "c:/tmp/ms_tmp/"

The second alias line configures the location of temporary files created by PHP/Mapscript. You will have to adjust the RAPC sources to use the same alias and path. Adjust the path names according to your RAPC installation path.

The PHP scripting language is available from www.php.net.

RAPC is currently using PHP 4.*. Use of RAPC with PHP 5.0 will require some small changes to the application and is not recommended yet. Please contact the RAPC developers if PHP 5.0 is a requirement for your installation.

Follow the installation instructions in the PHP documentations.

	Note
	If you don't install PHP to c:\windows\php, some of the settings below have to be adjusted.

	Caution
	Because of previous PHP/Mapscript limitations, it is recommended to install PHP as a CGI command. The use of PHP as an Apache module is not very well tested with RAPC and may lead to instabilities. If you are testing such a setup, please share your experiences with the RAPC developers.

The installation can be completed with the following three lines in httpd.conf:

ScriptAlias /php/ "c:/windows/php/"
AddType application/x-httpd-php .php
Action application/x-httpd-php "/php/php.exe"

Again, make sure that the path names above match the ones on your system.

Add the following RAPC-specific configuration settings to c:\windows\php.ini:

default_mimetype = "text/html"
default_charset = "utf-8"

include_path = ".;c:\windows\php\pear"

error_reporting  =  E_ALL & ~E_NOTICE

extension_dir = "c:/windows/php/extensions"
enable_dl = On

allow_call_time_pass_reference = On

file_uploads = On
upload_tmp_dir = c:\tmp
upload_max_filesize = 20M

extension=php_gd2.dll
extension=php_gettext.dll
extension=php_pgsql.dll
extension=php_zip.dll
extension=php_dbx.dll
extension=php_oci.dll
extension=php_pgsql.dll
extension=php_mapscript_46.dll

[Session]
session.save_path = c:/tmp
      

	Caution
	In order to use gettext in PHP on Linux, the PHP safe mode has to be enabled. The reason is that the putenv() function to set the locale will fail otherwise. In php.ini: safe_mode = On

On Windows, install the mapserver distribution with PHP/Mapscript, which is available from the internet under http://maptools.org.

On other operating systems, install PHP/Mapscript from the Mapserver distribution which is available from http://mapserver.gis.umn.edu/index.html.

Make sure that the PHP/Mapscript extension is loaded in php.ini.

	Note
	You'll need a PHP/Mapscript binary compiled with PostGIS support.

Active Perl is a PERL distribution for Windows.

It is freely available from http://www.activestate.com.

PERL is the programming language used for some PostGIS maintenance tools like postgis_restore.pl.

On other operating systems like Linux, you will most likely be able to use the PERL distribution that is already installed.

GIX is an ArcView 3.* extension that allows to export views to mapserver map files.

GIX is available from http://gix.sourceforge.net.

	Note
	You can only use fragments from the map files created by GIX as ArcView 3.* does not support PostGIS.

See Section 5.2, “Custom Map” for details regarding the RAPC map files.

To edit the rapc.po files, poEdit is recommended. It is freely available from http://poedit.sourceforge.net.

	Tip
	Install poEdit version 1.3.1 or higher.

In order to extract the translation messages from the PHP sources, the following settings should be applied.

Start poEdit.

Select Preferences from the File menu.

Select the Parser tab and click on the New button.

Figure 42. poEdit PHP parser settings

Close the dialogs.

Open a rapc.po file.

Choose Options... from the Catalog menu.

In the Paths tab, add the path to the RAPC source as shown in Figure 43, “Catalog Path”

Figure 43. Catalog Path

	Caution
	Make sure that you enter the actual path to the RAPC sources on your system.

Once the settings above have been applied, it is possible to update the catalog by selecting Update from sources from the Catalog menu.

See also Section 3.4, “Translation System”.

The RAPC application replaces the dummy user name and password in the mapfile with the information provided by the user when logging on. Example 1, “PostGIS Connection Example” shows an example PostGIS connection line from a mapfile.

CONNECTION "dbname=rapc user=dummy password=dummy host=localhost"
	    

	Important
	Make sure that the PostgreSQL "rapcuser" group has the right to select from the tables used for your PostGIS layers.

Plug-ins for the identify tool of the map page allow to extend the functionality of the application.

The plug-ins are configured in conf/identifyplugin.ini. The file is a simple text file that can be edited with any text editor.

; Configuration file for map.php plug-ins
[IdentifyPlugin]
Plugin1 = ImageIdentifyPlugin
Layer1 = Panel
;Plugin2 = ???
;Layer2 = ???

Note that identifyplugin.ini can also contain configuration options for the individual plug-ins (in different sections). See the "[Plugin1]", "[Plugin2]", ... sections for details.

The RAPC application allows to load GIS data in shapefile format through a web interface. Log in using a RAPC account with administrator rights, e.g. admin. Zip the shapefile before uploading.

See the RAPC User Guide for details on the shapefile loader.

	Note
	Data that is edited in RAPC uses sequences to determine the next primary key. For this reason it might be necessary to adjust a sequence if certain shapefiles are loaded.

The commandline tool shp2pgsql is part of the PostGIS distribution and used internally by the RAPC shapefile loader web interface. It allows to load shapefiles to PostGIS tables.

Make sure that shp2pgsql.exe and psql.exe are in the path:

PATH=%PATH%;c:\Program Files\PostgreSQL\8.0\bin
	  

If necessary, adjust the encoding used by psql through the PGCLIENTENCODING environment variable:

set PGCLIENTENCODING=WINDOWS-1256

If the table does not exist in your database yet, omit the "-d" option when calling shp2pgsql. See the shp2pgsql documentation for details.

Recreate the views if necessary:

	Tip
	You can use pgAdmin III as well as the commandline tools pg_dump or pg_dumpall to backup your RAPC database. Please refer to the pgAdmin III and PostgreSQL documentation for detailed information on how to perform the backups. In addition, the instructions below explain how to backup the database using the PostgreSQL command line tool pg_dumpall.

For all GIS data displayed in the RAPC maps, follow your usual backup strategies.

In order to backup the content of the RAPC database, do the following:

	Important
	Make sure that you also backup your map and configuration and symbol files (c:\Program Files\rapc\include\dcmconfig.php and all files under c:\Program Files\rapc\conf).

	Tip
	Restore is available through pgAdmin III as well as the commandline tools psql or pg_restore. Please refer to the pgAdmin III and PostgreSQL documentation for details how to restore a database dump. In addition, the instructions below explain how to restore the database using the PostgreSQL command line tool psql.

Restore all the GIS data used in the map from your GIS data backups.

In order to restore a previous dump file of the RAPC database, execute the following commands:

Remove old files from c:\tmp and c:\tmp\ms_tmp.

	Caution
	Be careful not to delete the c:\tmp\ms_tmp folder itself. If you delete the folder by accident, recreate it immediately.

The RAPC installer schedules a task that runs the script c:\program files\rapc\script\recreate_tmp.bat every day at 12:01.

The Schedule can be changed or deleted through the Windows Task Scheduler:

All data related to the RAPC business processes should be checked, at least with some samples.

The following list is a preliminary list of checks that should be performed:

	Tip
	Try to reboot the machine. Alternatively, log on as administrator and restart the service. The most common startup problem is a leftover postmaster.pid file.

If the PostgreSQL Database Server service fails to start, the Windows event log might provide useful information.

	Caution
	If the PostgreSQL service fails to start make sure that there is no file named c:\program.