< User Manual

Structure >

## 1. Installation

## 1.1. CartoWeb Installation

### 1.1.1. Prerequisite for Installing CartoWeb

CartoWeb depends on several software components for its proper working. Some are required and others are optional, depending on what you intend to do.

### Note

Windows users can ignore this chapter and go directly to Section 1.1.2, “CartoWeb Download”

The required software are:

A Web Server

  Such as Apache http://httpd.apache.org

PHP >= 5.0.3

  See http://www.php.net for more informations. You will need to have some features available in PHP:
  - Gettext (optional): You need the Gettext module if you want to enable the Internationalization in CartoWeb. See Chapter 16, Internationalization for configuration.

    ### Note

    If you are using the demo, you need to have Gettext support installed, as it uses Gettext by default.

    If you are using Cygwin, simply install the gettext-devel package.
  - SOAP (optional if using direct mode only): You need the SOAP module if you want to use CartoWeb as a Webservice or with separated CartoClient and CartoServer. This is related to the `cartoserverDirectAccess` parameter described in Section 4.2, “ `client.ini` ”

  ### Note

  If you are using Windows, simply use the Windows Installer Section 1.1.2, “CartoWeb Download”. If you absolutely want to install PHP manually, see Appendix B, Apache & Mapserver Windows Manual Installation.

MapServer PHP/MapScript (from MapServer >= 4.4)

  See http://www.maptools.org/php_mapscript/ for more information and installation instructions.

  ### Note

  If you are using Debian, and you need to install MapServer, you can have a look at Appendix A, Mapserver Debian Installation

  ### Note

  If you are using Windows, simply use the Windows Installer Section 1.1.2, “CartoWeb Download”. If you absolutely want to install MapServer manually, see Appendix B, Apache & Mapserver Windows Manual Installation.

PostgreSQL with PostGIS Support (Optional)

  If you want spatial database support in CartoWeb you will need to install PostGIS of the PostgreSQL database. See http://postgis.refractions.net/ for more information.

### 1.1.2. CartoWeb Download

There are two ways to get CartoWeb:

1. Complete package from the official website:

   - Download CartoWeb package from http://cartoweb.org/downloads.html. It is recommended that you download the version with demo for a better user experience.
   - Uncompress the archive somewhere in your path accessible by your web server.

2. From CVS: Get the current development version via CVS using the following command:

       cvs -d :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public co cartoweb3

   From CVS with cw3setup.php: If you already have the `cw3setup.php` file, which comes along the CartoWeb package or CVS source, you can fetch CartoWeb from CVS and set up it at once. See Section 1.1.3.2.6, “Install or Reinstall CartoWeb from CVS and Set Up It at Once” for more details.

Once you have CartoWeb, point your web browser to the file located in `htdocs/info.php`, and check that the PHP information page displays correctly (meaning PHP is correctly setup) and that you have do not have a WARNING message at the top of the page about MapScript failing to load. If it is not the case, CartoWeb will not run correctly. You should install and set up PHP and PHP/MapScript correctly. See Section 1.1.1, “Prerequisite for Installing CartoWeb”.

Having Gettext installed is recommended if you wish to use the multilingual features of CartoWeb.

### 1.1.3. Command Line Installation

CartoWeb installer is `cw3setup.php`, located in the root directory of the application.

You can run this file with the `--help` parameter to see the available options. For instance:

    <PHP-INTERPRETER> cw3setup.php --help

where <PHP-INTERPRETER> is the location of your php interpreter. On Windows, it can be `C:\ms4w\Apache\cgi-bin\php.exe` or on Unix `/usr/lib/cgi-bin/php`.

### Note

There is a deployment mechanism to automate CartoWeb installation and updates. If you are using different servers like: development, tests and production, it is highly recommended to use it: http://www.cartoweb.org/cwiki/AutomaticDeployment/

#### 1.1.3.1. List of Available Options

    Usage: cw3setup.php ACTION [OPTION_1] ... [OPTION_N]

    Possible actions:

     --help, or -h              Display this help and exit.
     --version or -v            Output version information and exit.
     --install                  Install CartoWeb.
     --fetch-demo               Fetch the demo data from cartoweb.org, and extract
                                it in the demo project if not already there.
     --clean                    Clean generated files and caches.

    List of options:

     --debug                    Turn on output debugging.

     --writableowner OWNER      The user who should have write permissions for
                                generated files.

     --cvs-root                 CVS Root directory to use when fetching
                                CartoWeb/project out of CVS.
     --fetch-from-cvs           Fetch CartoWeb from CVS and install it in the
                                current directory, or in the directory given by
                                the --install-location parameter.
                                NOTE: You must be located where cartoweb3 directory
                                will be created, not inside like other commands.
     --cartoweb-cvs-option OPTIONS  A string which will be given to the cvs checkout
                                command of cartoweb (not projects!).
                                For instance, to fetch a specific branch,
                                use '-r MY_BRANCH'. Or for a specific date,
                                use '-D "2005-09-05 11:00"'.
     --fetch-from-dir DIRECTORY Copy CartoWeb from the specified directory into the
                                current directory, or in the directory given by the
                                --install-location parameter.
                                NOTE 1: You must be located where cartoweb3
                                directory will be created, not inside like other
                                commands.
                                NOTE 2: You may either use a path relative to the
                                target cartoweb3 directory or an absolute path.
     --install-location         Directory where to install CartoWeb
                                (when using --fetch-from-cvs/dir options).

     --delete-existing          Overwrite existing directories if any.
     --no-symlinks              Do not use symbolic links, even if your operating
                                system supports them.

     --config-from-file FILE    Location of a configuration file for automatic
                                variable replacement in .in files.
                                NOTE: You may either use a path relative to the
                                target cartoweb3 directory or an absolute path.
     --config-from-project PROJECT Read the configuration file containing variables
                                to replace in .in files from the specified project.

     --fetch-project-cvs PROJECT Fetch the given project from CVS (see --cvs-root
                                option). To fetch several projects at a time,
                                specify this option as many times as necessary.
     --fetch-project-svn PROJECT Fetch the given project from SVN (you will need to
                                give --svn-co-options to specifiy the checkout
                                command to be used).
                                To fetch several projects at a time,
                                specify this option as many times as necessary.
     --svn-co-options           Checkout command to use for fetching project with
                                SVN. For instance "--username foo --no-auth-cache
                                checkout https://myproject/svn/bar/".
     --fetch-project-dir DIRECTORY Fetch the given project from a directory. To
                                fetch several projects at a time, specify this
                                option as many times as necessary.
     --project PROJECT          Installation is launched only for given project. To
                                install several projects at a time, specify this
                                option as many times as necessary.

     --default-project PROJECT  Default project to use.
     --base-url BASEURL         URL where you can find client.php.
     --profile PROFILENAME      The profile to use (development/production/custom).
                                NOTE: default is 'development'
     --clean-views              Clean views (must be used with --clean).
     --clean-accounting         Clean accounting (must be used with --clean).
     --keep-directories         Do not remove the generated directories during
                                cleaning (must be used with --clean).
     --keep-permissions         Do not alter the permissions of writable directories.

#### 1.1.3.2. Examples of Use

##### 1.1.3.2.1. Basic Setup

To perform a basic setup of CartoWeb, such as if you want to run the demo project, type:

    <PHP-INTERPRETER> cw3setup.php --install --base-url
                http://www.example.com/cartoweb

In this example, http://www.example.com/cartoweb is the address which corresponds to the `cartoweb3/htdocs` directory. You should find `client.php` if you type this URL.

##### 1.1.3.2.2. Installing a Project from a Directory

    <PHP-INTERPRETER> cw3setup.php --install --fetch-project-dir
                /home/foo/my_project --base-url http://www.example.com/cartoweb

##### 1.1.3.2.3. Updating CartoWeb after Modifications

When you modify or add new content/features to CartoWeb, you need to update it. This will set relative links or copy new/modified resources files (templates, images, new plugins, ...)

    <PHP-INTERPRETER> cw3setup.php --install --base-url
                http://www.example.com/cartoweb

Same as Section 1.1.3.2.1, “Basic Setup”. Existing files are not overwritten.

##### 1.1.3.2.4. Cleaning Generated Files (Map, PDF, Temporary Files and Smarty Cache)

    <PHP-INTERPRETER> cw3setup.php --clean

##### 1.1.3.2.5. Fetching the Demo Data

    <PHP-INTERPRETER> cw3setup.php --fetch-demo

##### 1.1.3.2.6. Install or Reinstall CartoWeb from CVS and Set Up It at Once

###### 1.1.3.2.6.1. Install

    <PHP-INTERPRETER> cw3setup.php --install --cvs-root
                  :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public
                  --fetch-from-cvs --base-url http://www.example.com/cartoweb

### Note

Do no execute this command from the `cartoweb3` folder! Because this will fetch the whole cartoweb3 hierarchy from cvs, including the `cartoweb3` folder. If you executed this from the `cartoweb3` folder you would end up with something like `cartoweb3/cartoweb3/...`. Instead, copy the `cw3setup.php` in the parent directory, delete (or backup) the cartoweb3 folder and execute the command.

###### 1.1.3.2.6.2. Reinstall

    <PHP-INTERPRETER> cw3setup.php --install --cvs-root
                  :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public
                  --fetch-from-cvs --delete-existing
                  --base-url http://www.example.com/cartoweb

### Warning

This command will automatically delete the existing `cartoweb3/` folder! Be sure to backup the files and projects you wish to keep.

### Note

See note on Section 1.1.3.2.6.1, “Install”. Notice here the --delete-existing parameter. Needed here because `cartoweb3/` already exists. Without it the cw3setup script issues a warning and stops.

##### 1.1.3.2.7. Update CartoWeb from CVS

To keep your CartoWeb up-to-date with the development version, simply type the following command in the `CartoWeb` root folder:

    cvs -d :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public update

### Warning

This may have some serious effects on your existing developments, it is recommended you backup the CartoWeb root folder and all subforders before execution.

### 1.1.4. Windows Installation

#### 1.1.4.1. Windows Install with Win32 Installer (Recommended)

- Download the MS4W installer at http://www.maptools.org/dl/ms4w/ms4w-2.2.4-setup.exe. Double-click on the executable to launch it. This will install Apache with PHP5.2.3, 4.10.2 CGI and MapScript.
- Download the CartoWeb installer at http://cartoweb.org/downloads.html. Double-click on the executable to launch it. This will install CartoWeb. You can also optionaly install the cartoweb demo data and Gettext (for internationalisation).
- You need to reboot Windows after the installation if you want to use the internationalisation system with Gettext .
- That's it! Point your browser to http://localhost/cartoweb3/htdocs/client.php.

Once it is installed, you can modify CartoWeb setup with the command-line script `cw3setup.php` (Section 1.1.3, “Command Line Installation”) from either a DOS or a Cygwin prompt. See Section 1.1.4.3, “CartoWeb Setup” for more info about how to use those interfaces.

#### 1.1.4.2. Windows Manual Install

Instructions for Apache/PHP and MapServer installation are given in Appendix B, Apache & Mapserver Windows Manual Installation

Then download CartoWeb as described above (Section 1.1.2, “CartoWeb Download”).

Eventually set CartoWeb up with the command-line script `cw3setup.php` (Section 1.1.3, “Command Line Installation”) from either a DOS or a Cygwin prompt. See Section 1.1.4.3, “CartoWeb Setup” for more info about how to use those interfaces.

#### 1.1.4.3. CartoWeb Setup

##### 1.1.4.3.1. CartoWeb Setup with DOS

Open a command prompt (Start menu > Run > "cmd") and go to the CartoWeb root:

    cd C:\ms4w\apps\cartoweb3

Then see Section 1.1.3.2.1, “Basic Setup”

### Note

To enable you to execute PHP scripts easily (like `php cw3setup.php --someparameters` instead of `C:\ms4w\Apache\cgi-bin\php.exe cw3setup.php --someparameters`), set the path to the PHP binary in your PATH environment variable (control panel > system > Advanced > Environment Variables. If there is no PATH variable, add a new one. If a PATH variable is already present, you can add the path to php.exe at the end of the existing path values, but add a ";" inbetween: path1;path2;path3):

    C:\ms4w\Apache\cgi-bin;

The example above is true if the PHP binary are installed in `C:\ms4w\Apache\cgi-bin`.

### Note

If you are using the demo, you need to have Gettext support installed, as it uses Gettext by default. If you used the win32 installer, Gettext is already installed, otherwise you must install it manually. You can get a version of Gettext for Windows there http://gnuwin32.sourceforge.net/packages/gettext.htm. Also set the path to the Gettext binary in your PATH environment variable.

    C:\Program Files\GnuWin32\bin;

The example above is true if the Gettext binaries are installed in `C:\Program Files\GnuWin32\bin`. This is needed by the `po2mo.php` script to merge and compile the languages translation files.

### Note

If you intend to use CVS in command line, you need to install a CVS client. Use WinCVS or TortoiseCVS, both are free Open Source clients. You must add the path to the CVS binary in your PATH environment variable.

    C:\Program Files\TortoiseCVS;

The example above is true if you installed TortoiseCVS in `C:\Program Files\TortoiseCVS`.

##### 1.1.4.3.2. CartoWeb Setup with Cygwin

Open a Cygwin window and go to the CartoWeb root:

    cd C:
    cd ms4w/apps/cartoweb3/

Then see Section 1.1.3.2.1, “Basic Setup”

### Note

You can download Cygwin here Cygwin . When you install Cygwin, be sure to select the packages tar (or unzip) and cvs. You can also install the gettext-devel package, so you wont need to get an external gettext installation later. If you have already installed Cygwin, type the following command to see what package are currently installed.

    cygcheck -c

If the packages mentioned above are not present, run Cygwin setup again and add the missing packages.

### Note

To enable you to execute PHP scripts easily, set the path to the PHP binary in your `.bashrc` (in `C:\cygwin\home\Administrator\` by default):

    export PATH=$PATH:/cygdrive/c/ms4w/Apache/cgi-bin

The example above is true if the PHP binary are installed in `C:\ms4w\Apache\cgi-bin`.

If you do not want to install the cvs and gettext Cygwin package, you need to add also the path to the external CVS and gettext binaries.

    export PATH=$PATH:/cygdrive/c/program Files/GnuWin32/bin
    export PATH=$PATH:/cygdrive/c/program Files/TortoiseCVS

See the note in Section 1.1.4.3.1, “CartoWeb Setup with DOS”

## 1.2. Demos

### 1.2.1. Introduction

A few demos are embedded in CartoWeb to demonstrate the range of functionalities that CartoWeb offers and give users examples on how to implement them:

- demoCW3: this is an overview of the standard functionalities that are somehow visible for an end-user in CartoWeb,
- demoPlugins: it shows the new functionalities that are available in latest CartoWeb versions,
- demoEdit: a simple demonstration of the geographical objects edition and persistent storage tools.
- demoToolTips: it demonstrates the usage of the tooltips using pseudo real data. Follow the installation notes below and also the specific database installation in Section 1.2.5, “ToolTips demo specific installation”

Demo data are freely downloadable. Next section explains how to install them. Configuration and programming details are then described.

### 1.2.2. Installation

Before installing these demos, you need to have a working CartoWeb installation. You can refer to the previous chapters how to install it.

To install the demoCW3 project, you need to gather the data by launching the cw3setup.php with the --fetch-demo option.

On the other hand, the demoPlugins project uses plugins that work with databases. Consequently some databases settings and configuration are required. We describe here how to install these databases and how to use cw3setup.php.

Step by step guide:

1. Install PostgreSQL with PostGIS support. Prerequisite: Postgresql >= 8.0

   ### Note

   If you are on Debian, you can have a look at Appendix A, Mapserver Debian Installation

2. Create a PostgreSQL database using the following command:

       $ createdb demo_plugins

3. Integrate PostGIS functionalities in this database. Typically, you can type:

       $ createlang plpgsql demo_plugins
       $ psql -d demo_plugins -f lwpostgis.sql
       $ psql -d demo_plugins -f spatial_ref_sys.sql

   ### Note

   psql is a terminal-based front-end for PostgreSQL. It enables you to type in queries interactively, issue them to PostgreSQL, and see the query results. Don't forget to specify its location on your system to use it. If the lwpostgis.sql and spatial_ref_sys.sql files aren't in the current directory, you have to specify their path.

4. Create tables used by the locate plugin to allow you to do a recenter on features by searching their names. To do so, you should export the free downloadable layers airport, agglo, district and town in PostgreSQL/PostGIS tables by typing the following command:

       $ shp2pgsql -I aerofacp.shp airport > /tmp/airport.sql
       $ psql -d demo_plugins -f /tmp/airport.sql

       $ shp2pgsql -I builtupa.shp agglo > /tmp/agglo.sql
       $ psql -d demo_plugins -f /tmp/agglo.sql

       $ shp2pgsql -I polbnda.shp district > /tmp/district.sql
       $ psql -d demo_plugins -f /tmp/district.sql

       $ shp2pgsql -I mispopp.shp town > /tmp/town.sql
       $ psql -d demo_plugins -f /tmp/town.sql

   ### Note

   shp2pgsql is a command-line program that exports a shapefile into SQL commands. Don't forget to specify its location on your system to use it. You have to specify the path to the shapefiles if they aren't in the current directory.

5. Execute `cw3setup.php`. file, with the --fetch-demo option to download geographical data.

6. cw3setup.php Options. To finish demoPlugins installation, you will need to launch the `cw3setup.php` with the --config-from-file parameter pointing to a property file containing database configuration informations. Such a file is provided in the `cartoweb3/projects/demoPlugins/demo.properties` file. You need to edit this file and change the parameter to match your environment. In particular the DB_HOST, DB_USER, DB_PASSWD and DB_PORT options need to match your database access configuration. DB_LOCATE_NAME must be set to the name of the database for the locate plugin. This file contains comments about the description of each variables. Here's an example how to call the cw3setup.php script with the --config-from-file option.

       php cw3setup.php --install --base-url http://www.example.com/cartoweb
                       --config-from-file projects/demoPlugins/demo.properties

### Note

Routing fonctionnalities are also integrated in this demo. But they need a more advanced configuration and the PgRouting module installed in the database, so they aren't integrated in the basic installation. The steps to integrate routing fonctionnalities and create database tables are described in a dedicated chapter of the User Documentation: Chapter 26, Routing Plugin

### 1.2.3. Routing specific installation

Routing installation instructions have moved to a dedicated chapter in the User Documentation: Chapter 26, Routing Plugin

### 1.2.4. Locate Plugin specific installation

This plugin allows user to search features by their names, and recenter on them.

By typing the first letters of a name, user is given a list of corresponding names. Clicking on one of them recenters the map on it.

### Note

In the `locate.ini`, you also need to specify the layers on which you want to do a search by name and the sql statements to request the database.

### Tip

Ensure that the tables have the correct privileges (GRANT SELECT) in the database.

### 1.2.5. ToolTips demo specific installation

### Tip

The database used to store data is the same as for the demoPlugins

- Create the tables for layers radio and gsm.

  ### Note

  To do so, convert the radio and gsm data from shapefile to postGIS tables. The shapefiles should be available in `projects/demoCW3/server_conf/demoCW3/data` where all demos data are.

      $ shp2pgsql -I radio.shp radio > /tmp/radio.sql
      $ psql -d demo_plugins -f /tmp/radio.sql

      $ shp2pgsql -I gsm.shp gsm > /tmp/gsm.sql
      $ psql -d demo_plugins -f /tmp/gsm.sql

- Create the table for channel data.

      $ psql -d demo_plugins -f channels.sql

  The `channels.sql` is located in the `projects/demoToolTips/server_conf/demoToolTips/sql` folder

- Launch the install script in your CartoWeb root directory.

      php cw3setup.php --install --base-url <base-url> --profile development
                       --project demoToolTips --config-from-file projects/demoPlugins/demo.properties

### 1.2.6. Plugins extensions further information

The aim of this part is to give you further informations on creation of demoPlugins and demoEdit plugins extensions. If you create a new plugin or adapt an existing one, we guess it will be helpful to take these plugins extensions for example or use one of these two resources:

- User HowTo: http://www.cartoweb.org/cwiki/HowTo,
- Dev tutorial new plugins part: Chapter 2, New Plugins.

#### 1.2.6.1. demoRouting Extension

Routing installation instructions have moved to a dedicated chapter in the User Documentation: Chapter 26, Routing Plugin

#### 1.2.6.2. demoEdit Extension

Some useful tips are available in Section 14.3, “How To”.