<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % cartoweb SYSTEM "../cartoweb.ent" >
  %cartoweb;
]>

<!-- $Id: install.xml,v 1.58 2007-07-26 14:24:21 olivier Exp $ -->

<chapter id="user.install">
  <title>Installation</title>

  <sect1 id="user.install.main">
    <title>&cartoweb; Installation</title>

    <sect2 id="user.install.main.prerequisite">
      <title>Prerequisite for Installing &cartoweb;</title>
      <para>&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>
          <para> Windows users can ignore this chapter and go directly to 
            <xref linkend="user.install.main.download"/></para>
        </note>
        </para>

      <para>The required software are:
        <variablelist>
            <title>A Web Server</title>
            <varlistentry><term></term>
              <listitem>
                <para>Such as Apache <ulink url="http://httpd.apache.org"/></para>
              </listitem>
            </varlistentry>
        </variablelist>
        <variablelist>
          <title>PHP >= 5.0.3</title>
          <varlistentry><term></term>
            <listitem>
              <para> See <ulink url="http://www.php.net"/> for more informations.
                You will need to have some features available in PHP:
                <itemizedlist>
                  <listitem>
                    <para><emphasis>Gettext</emphasis> (optional): You need the Gettext module if you want
                      to enable the Internationalization in &cartoweb;. See
                      <xref linkend="user.i18n"/> for configuration.
                      <note>
                        <para> If you are using the demo, you need to have Gettext
                          support installed, as it uses Gettext by default.
                        </para>
                      </note>
                      If you are using Cygwin, simply install the <emphasis>gettext-devel</emphasis> package.
                    </para>
                  </listitem>
                  <listitem>
                    <para><emphasis>SOAP</emphasis> (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 <literal>cartoserverDirectAccess</literal> 
                    parameter described in <xref linkend="user.config.client"/></para>
                  </listitem>
                </itemizedlist>
                <note><para>
                If you are using Windows, simply use the Windows Installer 
                <xref linkend="user.install.main.download"/>. If you absolutely want to install 
                PHP manually, see <xref linkend="appendix.windows_manual_install"/>.
              </para></note>
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <title>MapServer PHP/MapScript (from MapServer &gt;= 4.4)</title>
          <varlistentry><term></term>
            <listitem>  
              <para>See <ulink url="http://www.maptools.org/php_mapscript/"/>
                for more information and installation instructions.</para>
              <note><para>
                If you are using Debian, and you need to install MapServer, you can have a 
                look at <xref linkend="appendix.debian_mapserver"/>
              </para></note>
              <note><para>
                If you are using Windows, simply use the Windows Installer 
                <xref linkend="user.install.main.download"/>. If you absolutely want to install 
                MapServer manually, see <xref linkend="appendix.windows_manual_install"/>.
              </para></note>
            </listitem>
          </varlistentry>
        </variablelist>
        <variablelist>
          <title>PostgreSQL with PostGIS Support (Optional)</title>
          <varlistentry><term></term>
            <listitem>
              <para>If you want spatial database support in &cartoweb; you
              will need to install PostGIS of the PostgreSQL database.
              See <ulink url="http://postgis.refractions.net/"/> 
              for more information.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </sect2>
    
    <sect2 id="user.install.main.download">
      <title>CartoWeb Download</title>
      <para>
      There are two ways to get &cartoweb;:
      </para>
      <orderedlist>
        <listitem>
          <formalpara><title>Complete package from the official website:</title>
            <para>
              <itemizedlist mark='opencircle'>
                <listitem>
                  <para>Download &cartoweb; package from <ulink url="http://cartoweb.org/downloads.html"/>.
                    It is recommended that you download the version with demo for a better
                    user experience.</para>
                </listitem>
                <listitem>
                  <para>
                    Uncompress the archive somewhere in your path accessible by your web 
                    server.
                  </para>
                </listitem>
              </itemizedlist>
            </para>
          </formalpara>
        </listitem>
        <listitem>
          <formalpara><title>From CVS:</title>
            <para>Get the current development version via CVS using the following command:
            <screen><![CDATA[cvs -d :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public co cartoweb3]]></screen>
            </para>
          </formalpara>
          <formalpara><title>From CVS with cw3setup.php:</title>
            <para>If you already have the <filename>cw3setup.php</filename> file, which comes along the &cartoweb; package 
            or CVS source, you can fetch &cartoweb; from CVS and set up it at once. See 
            <xref linkend="user.install.main.setup.example.reinstall"/> for more details.</para>
          </formalpara>
        </listitem>
      </orderedlist>
      <para>
        Once you have &cartoweb;, point your web browser to the file located in 
        <filename>htdocs/info.php</filename>, 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 
          <xref linkend="user.install.main.prerequisite"/>.
      </para>
      <para>
        Having Gettext installed is recommended if you wish to use the multilingual features of &cartoweb;.
      </para>
    </sect2>

    <sect2 id="user.install.main.setup">
      <title>Command Line Installation</title>
      <para>
        &cartoweb; installer is <filename>cw3setup.php</filename>, located in the root directory of the application.
      </para>
      <para>
        You can run this file with the <literal>--help</literal> parameter to see the 
        available options. For instance:
        <screen>&lt;PHP-INTERPRETER&gt; cw3setup.php --help</screen>
        where &lt;PHP-INTERPRETER&gt; is the location of your php interpreter. On
        Windows, it can be <literal>C:\ms4w\Apache\cgi-bin\php.exe</literal> or on Unix
        <literal>/usr/lib/cgi-bin/php</literal>.
      </para>
      <para>
       <note>
         <para>
       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:
       <ulink url="http://www.cartoweb.org/cwiki/AutomaticDeployment/"/>
      </para>
       </note>
      </para>

      <sect3 id="user.install.main.setup.commands.list">
        <title>List of Available Options</title>
        <para>
          <screen><![CDATA[
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.]]></screen>
        </para>
      </sect3>

      <sect3 id="user.install.main.setup.example">
        <title>Examples of Use</title>
        <sect4 id="user.install.main.setup.example.basic">
          <title>Basic Setup</title>
          <para>
            To perform a basic setup of &cartoweb;, such as if you want to run the demo project, type:
            <screen>&lt;PHP-INTERPRETER&gt; cw3setup.php --install --base-url 
            http://www.example.com/cartoweb</screen>
            In this example, http://www.example.com/cartoweb is the address which corresponds
            to the <literal>cartoweb3/htdocs</literal> directory. You should find 
            <literal>client.php</literal> if you type this URL.
          </para>
        </sect4>
        <sect4 id="user.install.main.setup.example.directory">
          <title>Installing a Project from a Directory</title>
          <para>
            <screen>&lt;PHP-INTERPRETER&gt; cw3setup.php --install --fetch-project-dir 
            /home/foo/my_project --base-url http://www.example.com/cartoweb</screen>
          </para>
        </sect4>
        <sect4 id="user.install.main.setup.example.update">
          <title>Updating &cartoweb; after Modifications</title>
          <para>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, ...)
            <screen>&lt;PHP-INTERPRETER&gt; cw3setup.php --install --base-url 
            http://www.example.com/cartoweb</screen>
            Same as <xref linkend="user.install.main.setup.example.basic"/>. Existing files 
            are not overwritten.
          </para>
        </sect4>
        <sect4 id="user.install.main.setup.example.clean">
          <title>Cleaning Generated Files (Map, PDF, Temporary Files and Smarty Cache)</title>
          <para>
            <screen>&lt;PHP-INTERPRETER&gt; cw3setup.php --clean</screen>
          </para>
        </sect4>
        <sect4 id="user.install.main.setup.example.demo">
          <title>Fetching the Demo Data</title>
          <para>
          <screen>&lt;PHP-INTERPRETER&gt; cw3setup.php --fetch-demo</screen>
          </para>
        </sect4>
        <sect4 id="user.install.main.setup.example.reinstall">
          <title>Install or Reinstall &cartoweb; from CVS and Set Up It at Once</title>
          <sect5 id="user.install.main.setup.example.reinstall.new">
            <title>Install</title>
            <para>
              <screen>&lt;PHP-INTERPRETER&gt; cw3setup.php --install --cvs-root 
              :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public
              --fetch-from-cvs --base-url http://www.example.com/cartoweb</screen>
              <note>
                <para>Do no execute this command from the <filename>cartoweb3</filename> folder! Because this will fetch 
                the whole cartoweb3 hierarchy from cvs, including the <filename>cartoweb3</filename> folder. If you 
                executed this from the <filename>cartoweb3</filename> folder you would end up with something like 
                <filename>cartoweb3/cartoweb3/...</filename>. Instead, copy the <filename>cw3setup.php</filename> in the parent directory, 
                delete (or backup) the cartoweb3 folder and execute the command. 
                </para>
              </note>
            </para>
          </sect5>
          <sect5 id="user.install.main.setup.example.reinstall.over">
            <title>Reinstall</title>
            <para>
              <screen>&lt;PHP-INTERPRETER&gt; 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</screen>
              <warning><para>This command will automatically delete the existing <filename>cartoweb3/</filename> folder! Be sure to backup 
              the files and projects you wish to keep.</para></warning>
              <note>
                <para>See note on <xref linkend="user.install.main.setup.example.reinstall.new"/>. 
                Notice here the <emphasis>--delete-existing</emphasis> parameter. Needed here because 
                <filename>cartoweb3/</filename> already exists. Without it the cw3setup script issues a warning and stops.
                </para>
              </note>
            </para>
          </sect5>
        </sect4>
        <sect4 id="user.install.main.setup.example.cwupdate">
            <title>Update &cartoweb; from CVS</title>
            <para>To keep your &cartoweb; up-to-date with the development version, simply type 
            the following command in the <filename>&cartoweb;</filename> root folder:
            <screen><![CDATA[cvs -d :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public update]]></screen>
              <warning><para>This may have some serious effects on your existing developments, 
              it is recommended you backup the &cartoweb; root folder and all subforders before execution.</para></warning>
            </para>
        </sect4>
      </sect3>
    </sect2>

    <sect2 id="user.install.win32">
      <title>Windows Installation</title>

      <sect3 id="user.install.win32.installer">
        <title>Windows Install with Win32 Installer (Recommended)</title>
        <itemizedlist>
          <listitem>
            <para>
              Download the MS4W installer at <ulink url="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.
            </para>
          </listitem>
          <listitem>
            <para>
              Download the &cartoweb; installer at <ulink url="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).
            </para>
          </listitem>
          <listitem>
            <para>You need to reboot Windows after the installation if you want to use the internationalisation system with Gettext .</para>
          </listitem>
          <listitem>
            <para>
              That's it! Point your browser to <ulink url="http://localhost/cartoweb3/htdocs/client.php"/>.
            </para>
          </listitem>
        </itemizedlist>
        <para>
          Once it is installed, you can modify &cartoweb; setup with the command-line script <filename>cw3setup.php</filename> (<xref linkend="user.install.main.setup"/>) from either a DOS or a Cygwin prompt. See <xref linkend="user.install.win32.setup"/> for more info about how to use those interfaces.
        </para>
      </sect3>
      <sect3 id="user.install.win32.manual">
        <title>Windows Manual Install</title>
        <para>Instructions for Apache/PHP and MapServer installation are given in <xref linkend="appendix.windows_manual_install"/></para>
        <para>
          Then download &cartoweb; as described above (<xref linkend="user.install.main.download"/>). 
        </para>
        <para>
          Eventually set &cartoweb; up with the command-line script <filename>cw3setup.php</filename> (<xref linkend="user.install.main.setup"/>) from either a DOS or a Cygwin prompt. See <xref linkend="user.install.win32.setup"/> for more info about how to use those interfaces.
        </para>

      </sect3>
      <sect3 id="user.install.win32.setup">
        <title>&cartoweb; Setup</title>
        <sect4 id="user.install.win32.installer.dos">
          <title>&cartoweb; Setup with DOS</title>
          <para>Open a command prompt (Start menu > Run > "cmd") and go to the &cartoweb; root:
            <screen>cd C:\ms4w\apps\cartoweb3</screen>
            Then see <xref linkend="user.install.main.setup.example.basic"/>
            <note><para>To enable you to execute PHP scripts easily (like <parameter>php cw3setup.php --someparameters</parameter> 
              instead of <filename>C:\ms4w\Apache\cgi-bin\php.exe cw3setup.php --someparameters</filename>), 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):
              <screen><![CDATA[C:\ms4w\Apache\cgi-bin;]]></screen>
              The example above is true if the PHP binary are installed in <filename>C:\ms4w\Apache\cgi-bin</filename>.</para>
            </note>
            <note>
              <para> 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 
                <ulink url="http://gnuwin32.sourceforge.net/packages/gettext.htm" />.
                Also set the path to the Gettext binary in your PATH environment variable.
                <screen><![CDATA[C:\Program Files\GnuWin32\bin;]]></screen>
                The example above is true if the Gettext binaries are installed in <filename>C:\Program Files\GnuWin32\bin</filename>.
                This is needed by the <filename>po2mo.php</filename> script to merge and compile the languages translation files.
              </para>
            </note>
            <note>
              <para>If you intend to use CVS in command line, you need to install a CVS client. 
                Use <ulink url="http://www.wincvs.org/" >WinCVS</ulink> 
                or <ulink url="http://www.tortoisecvs.org/download.shtml" >TortoiseCVS</ulink>, both 
                are free Open Source clients. 
                You must add the path to the CVS binary in your PATH environment variable.
                <screen><![CDATA[C:\Program Files\TortoiseCVS;]]></screen>
                The example above is true if you installed TortoiseCVS in <filename>C:\Program Files\TortoiseCVS</filename>.
              </para>
            </note>
          </para>
        </sect4>
        <sect4 id="user.install.win32.installer.cygwin">
          <title>&cartoweb; Setup with Cygwin</title>
          <para>Open a Cygwin window  and go to the &cartoweb; root:
            <screen>
cd C:
cd ms4w/apps/cartoweb3/</screen>
            Then see <xref linkend="user.install.main.setup.example.basic"/>
          </para>
          <note><para>
            You can download Cygwin here <ulink url="http://www.cygwin.com/"><citetitle>Cygwin</citetitle>
            </ulink>. When you install Cygwin, be sure to select the packages <emphasis>tar</emphasis> 
            (or <emphasis>unzip</emphasis>) and <emphasis>cvs</emphasis>. You can also install the 
            <emphasis>gettext-devel</emphasis> 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.
            <screen>cygcheck -c</screen> If the packages mentioned above are not present, run Cygwin setup again 
            and add the missing packages.</para>
          </note>
          <note><para>
          To enable you to execute PHP scripts easily, set the path to the PHP binary in your 
            <filename>.bashrc</filename> (in <filename>C:\cygwin\home\Administrator\</filename> by default):
            <screen><![CDATA[export PATH=$PATH:/cygdrive/c/ms4w/Apache/cgi-bin]]></screen>
            The example above is true if the PHP binary are installed in <filename>C:\ms4w\Apache\cgi-bin</filename>.</para>
            <para>If you do not want to install the <emphasis>cvs</emphasis> and <emphasis>gettext</emphasis> Cygwin package, 
            you need to add also the path to the external CVS and gettext binaries. 
            <screen><![CDATA[export PATH=$PATH:/cygdrive/c/program Files/GnuWin32/bin
export PATH=$PATH:/cygdrive/c/program Files/TortoiseCVS]]></screen>
            See the note in 
            <xref linkend="user.install.win32.installer.dos"/></para>
          </note>
        </sect4>               
      </sect3>
    </sect2>
  </sect1>   
  <sect1 id="user.install.demo">
    <title>Demos</title>
    <sect2 id="user.install.demo.intoduction">
      <title>Introduction</title>
      <para>
        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:
        <itemizedlist>
          <listitem>
            <para><emphasis>demoCW3</emphasis>: this is an overview of the standard functionalities 
            that are somehow visible for an end-user in &cartoweb;,</para>
          </listitem>
          <listitem>
            <para><emphasis>demoPlugins</emphasis>: it shows the new functionalities that 
            are available in latest &cartoweb; versions,</para>
          </listitem>
          <listitem>
            <para><emphasis>demoEdit</emphasis>: a simple demonstration of the geographical objects 
            edition and persistent storage tools.</para>
          </listitem>
          <listitem>
            <para><emphasis>demoToolTips</emphasis>: it demonstrates the usage of the tooltips using 
            pseudo real data. Follow the installation notes below and also the specific database 
            installation in <xref linkend="user.install.demo.tooltips"/></para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        Demo data are freely downloadable. Next section explains how to install them. 
        Configuration and programming details are then described.
      </para>
    </sect2>
    <sect2 id="user.install.demo.quickinstall">
      <title>Installation</title>
      <para>
        Before installing these demos, you need to have a working &cartoweb; installation. You can refer to the previous chapters how to install it.
      </para>
      <para>
        To install the demoCW3 project, you need to gather the data by launching the <emphasis>cw3setup.php</emphasis> with the <emphasis>--fetch-demo</emphasis> option.
      </para>
      <para>
        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 <emphasis>cw3setup.php</emphasis>.
      </para>
      <para>
        Step by step guide:
      </para>
      <orderedlist>
        <listitem>
          <formalpara>
            <title>Install PostgreSQL with PostGIS support</title>
            <para>
              <emphasis>Prerequisite</emphasis>: Postgresql >= 8.0
              <note><para>
                If you are on Debian, you can have a look at <xref linkend="appendix.debian_mapserver"/>
              </para></note>
            </para>
          </formalpara>
        </listitem>
        <listitem>
          <formalpara>
            <title>Create a PostgreSQL database using the following command:</title>
            <para>
              <screen><![CDATA[$ createdb demo_plugins]]></screen>
            </para>
          </formalpara>
        </listitem>
        <listitem>
          <formalpara>
            <title>Integrate PostGIS functionalities in this database.</title>
            <para>
              Typically, you can type:
              <screen><![CDATA[
$ createlang plpgsql demo_plugins
$ psql -d demo_plugins -f lwpostgis.sql
$ psql -d demo_plugins -f spatial_ref_sys.sql]]></screen>
              <note><para>
                <emphasis>psql</emphasis> 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 <emphasis>lwpostgis.sql</emphasis> and <emphasis>
                spatial_ref_sys.sql</emphasis> files aren't in the current directory, you have to specify their path.
              </para></note> 
            </para>
          </formalpara>
        </listitem>
        <listitem>
          <formalpara>
            <title>Create tables used by the locate plugin to allow you to do a recenter
            on features by searching their names.</title>
            <para>  
              To do so, you should export the free downloadable layers <emphasis>airport, agglo, 
              district</emphasis> and <emphasis>town</emphasis> in PostgreSQL/PostGIS tables by typing 
              the following command:
              <screen><![CDATA[
$ 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]]></screen>
              <note><para>
                <emphasis>shp2pgsql</emphasis> 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.
              </para></note>
            </para>
          </formalpara>
        </listitem>
        <listitem>
          <formalpara>
            <title>Execute <filename>cw3setup.php</filename></title> 
            <para>
              file, with the <emphasis>--fetch-demo</emphasis> option to download geographical data.
            </para>
          </formalpara>
        </listitem>
        <listitem>
          <formalpara>
            <title>cw3setup.php Options</title>
            <para>
              To finish demoPlugins installation, you will need to launch the <filename>cw3setup.php</filename>
              with the <emphasis>--config-from-file</emphasis> parameter pointing to a property file 
              containing database configuration informations. Such a file is provided in the 
              <filename>cartoweb3/projects/demoPlugins/demo.properties</filename> file. You need to edit this file
              and change the parameter to match your environment. In particular the <emphasis>DB_HOST</emphasis>, 
              <emphasis>DB_USER</emphasis>, <emphasis>DB_PASSWD</emphasis> and <emphasis>DB_PORT</emphasis> options
              need to match your database access configuration.
              <emphasis>DB_LOCATE_NAME</emphasis> 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 <emphasis>cw3setup.php</emphasis> script with the 
              <emphasis>--config-from-file</emphasis> option.
              <screen><![CDATA[php cw3setup.php --install --base-url http://www.example.com/cartoweb 
                --config-from-file projects/demoPlugins/demo.properties]]></screen>
            </para>
          </formalpara>
        </listitem>
      </orderedlist>
      <para>
        <note><para>
        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: <xref linkend="user.routing"/>
        </para></note>
      </para>
    </sect2>
    <sect2 id="user.install.demo.routing">
      <title>Routing specific installation</title>
      <para>
        Routing installation instructions have moved to a dedicated chapter in the User Documentation:
        <xref linkend="user.routing"/>
      </para>      
    </sect2>
    <sect2 id="user.install.demo.locate">
      <title>Locate Plugin specific installation</title>
      <para>
        This plugin allows user to search features by their names, and recenter on them.
      </para>
      <para>
        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><para>
        In the <filename>locate.ini</filename>, 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.
        </para></note>
        <tip><para>
        Ensure that the tables have the correct privileges (GRANT SELECT) in
         the database.
        </para></tip>
      </para>
    </sect2>
    <sect2 id="user.install.demo.tooltips">
      <title>ToolTips demo specific installation</title>
      <para>
        <tip>
          <para>The database used to store data is the same as for the demoPlugins</para>
        </tip>
        <itemizedlist>
          <listitem>
            <formalpara>
              <title>Create the tables for layers radio and gsm</title>
              <para>
                <note><para>
                  To do so, convert the radio and gsm data from shapefile to postGIS tables.
                  The shapefiles should be available in 
                  <filename>projects/demoCW3/server_conf/demoCW3/data</filename> where all
                  demos data are.
                </para></note>
                <screen><![CDATA[
$ 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
]]></screen>
              </para>
            </formalpara>
          </listitem>
          <listitem>
            <formalpara>
              <title>Create the table for channel data</title>
              <para>
              <screen><![CDATA[$ psql -d demo_plugins -f channels.sql ]]></screen>
              The <filename>channels.sql</filename> is located in the 
              <filename>projects/demoToolTips/server_conf/demoToolTips/sql</filename>
              folder</para>
            </formalpara>
          </listitem>
          <listitem>
            <formalpara>
              <title>Launch the install script in your &cartoweb; root directory</title>
              <para>
                <screen><![CDATA[php cw3setup.php --install --base-url <base-url> --profile development
                 --project demoToolTips --config-from-file projects/demoPlugins/demo.properties]]></screen>
              </para>
            </formalpara>
          </listitem>
        </itemizedlist>
      </para>      
    </sect2>
    <sect2 id="user.install.demo.details">
      <title>Plugins extensions further information</title>
      <para>
        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:
        <itemizedlist>
          <listitem>
            <para>
              User HowTo: <ulink url="http://www.cartoweb.org/cwiki/HowTo"/>,
            </para>
          </listitem>
          <listitem>
            <para>
              Dev tutorial new plugins part: <xref linkend="dev.newplugin"/>.
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <sect3 id="user.install.demo.details.demoRouting">
        <title>demoRouting Extension</title>
        <para>
          Routing installation instructions have moved to a dedicated chapter in the User Documentation:
          <xref linkend="user.routing"/>
        </para>
      </sect3>
      <sect3 id="user.install.demo.details.demoEdit">
        <title>demoEdit Extension</title>
        <para>Some useful tips are available in <xref linkend="user.edit.howto"/>.</para>
      </sect3>
    </sect2>
  </sect1>
</chapter>
