Documentation

Installation
This tutorial will guide you through the initial steps to get up and
running with Cartaro. Because Cartaro is based on several open
source components, we need to make sure all requirements are met.
This guide is based on Ubuntu Precise (12.04 LTS). You might need to
adapt commands depending on your Linux distribution.

If you find the installation too complicated for a first sight at Cartaro
then you should try Cartaro on the OSGeo Live DVD or use the Docker
container for Cartaro.

Prerequisites
PostGIS 1.5 or later are supported by Cartaro's PostGIS module.
Apache and PHP requirements are set by Drupal and Tomcat
requirements are set by GeoServer.

First we install Apache, PHP, PostGIS, Tomcat and some additional

libraries using the following command:

sudo apt-get install unzip apache2 php5 php5-gd php5-curl php5-pgsql

postgresql-9.1 postgis postgresql-9.1-postgis postgresql-contrib-9.1 tomcat7

Now we are ready to create a PostGIS database where Drupal will be

installed and GeoServer will fetch spatial data from. Take a note of
database name, user name and password for the Drupal user we are
going to create. Replace DBUSER with the name of the user that you
want to provide to Drupal and DBNAME with the name of the database
that you want to use to store data entered in Cartaro. Afterwards it is
necessary to install PostGIS in the newly created database. For
PostGIS 1.5 execute the following commands:

sudo su postgres
createuser --pwprompt --no-superuser --no-createdb --no-createrole DBUSER
createdb --encoding=UTF-8 --owner=DBUSER DBNAME
psql -d "DBNAME" -f /usr/share/postgresql/9.1/contrib/postgis-1.5/postgis.sql
psql -d "DBNAME" -f /usr/share/postgresql/9.1/contrib/postgis_comments.sql
psql -d "DBNAME" -f /usr/share/postgresql/9.1/contrib/postgis-
1.5/spatial_ref_sys.sql
psql -d "DBNAME" -c 'grant all on geometry_columns to "DBUSER";'
psql -d "DBNAME" -c 'grant all on spatial_ref_sys to "DBUSER";'
exit

PostGIS 2.0 users should also grant access to geography_columns and

raster_columns.

Next you need to download and install GeoServer. Versions 2.2.x and
2.3.x has been tested with Cartaro:

wget
http://sourceforge.net/projects/geoserver/files/GeoServer/2.3.x/geoserver-
2.3.x-war.zip
sudo unzip geoserver-2.3.x-war.zip geoserver.war -d /var/lib/tomcat7/webapps/

GeoServer contains a default admin account with username "root" and

a random password. Either use this account when installing Cartaro, or
adapt the account to match your Drupal admin account. By default
GeoServer will be available at http://[host]:8080/geoserver.

Remember to set the JVM startup parameter ENABLE_JSONP=true for

GeoServer version 2.2.5 and above. Please consult the documentation
of your servlet container for instructions. Users of Tomcat 7 on Ubuntu
want to append to JAVA_OPTS in /etc/default/tomcat7. Note that despite
stated in GeoServer's documentation, only the JVM startup parameter
will work for all GeoServer versions.

JAVA_OPTS="${JAVA_OPTS} -DENABLE_JSONP=true"

It is also necessary to adapt the session timeout of GeoServer to

Drupal. Edit geoserver/WEB-INF/web.xml or [Tomcat]/conf/web.xml and set the
following session-config block inside the web-app block. After the Java
application server that is running GeoServer is restarted, everything is
ready to install Cartaro.
<web-app>
<session-config>
<session-timeout>33333</session-timeout>
</session-config>
...
</web-app>

The GeoServer module will authenticate Drupal users in GeoServer

even without web access to it. For GeoServer versions under 2.4.1,
additional configuration is necessary. The webLogin Filter
Authentication Chain should allow the creation of an HTTP session for
storing cookies. To configure this behaviour, in Security →
Authentication → Filter Chains click on webLogin and check Allow
creation of an HTTP session for storing the authentication token. Be
sure to click on save to maintain the new settings in Security →
Authentication page.

Cartaro Installation
Download and extract the distribution to a location of your choice
within your web server (e.g. /var/www/) and proceed with the installation
in the same way you'd install a plain Drupal as described in the
installation guide or just follow the steps outlined below.
Point your browser to the extracted Cartaro download within your
webserver to launch the graphical installer.

After Drupal verified its permission you are asked for the database
configuration.

During the installation you are asked to specify an existent GeoServer

instance. Ensure that your Drupal credentials match up with the
credentials for GeoServer or follow the documentation to share users
of Drupal and GeoServer.
Now, the installer will finally invite you to access your Cartaro.

If

you opted to install demo data your Cartaro will have some capital
cities predefined (content type Capital with title and coordinates).

Documentation
Getting Started
Once Cartaro is installed you will find yourself in a basically empty
Drupal instance. Of course if you've chosen to install sample data
these will now be present, too. The first steps are probably setting up
users, roles, content types and custom theme to suit your case.

Setting up content types

Content types are describing the fields and the structure of a specific
kind of content (e.g. the content type Capital contains the fields name
and location to generate content elements for the respective capitals
displayed on the map). To create a new content type, just follow the
steps below.

Log in with your administrative user (as created during Cartaro's

installation), then navigate to Structure → Content types and click Add
content type.

Choose a name and description for your content type and proceed
clicking Save and add fields.
Add a
new
field for
your
content
type by entering a descriptive name. We want to create a geospatial
field with the name Geometry. Select Geospatial data as field type and
OpenLayers Map as widget. Click Save to proceed to the field's
settings.
Choose your field settings in the new window: Select the geometry
type that describes the kind of geospatial information you want to

store. Choose Polygon to follow our example. Now click Save field
settings to go on.

The next screen asks for more settings of the newly created field. You
can now choose the map configuration and editor to use and select
the permitted amount of objects to draw on the map. The defaults
should be fine but check that OpenLayers Editor is set as OpenLayers
Behavior because that provides a nice editor for spatial data. Proceed
again with Save settings to finish the field creation.
Drupal directs you back to the list of attributes (manage fields screen)
but no other fields are necessary for the example. You have now
defined a content type with spatial data.

Under the tab Manage fields you could create further non-geospatial
fields. We don’t need to create a new one for our example.
Configuring GeoServer

GeoServer is used to provide layers via Web Feature Service (WFS) and
Web Map Service (WMS) with the geospatial field from your newly
created content type.

Choose Structure → GeoServer from the menu bar to visit the

GeoServer configuration page.
Creating a new layer in GeoServer

Use GeoServer layers to publish your geospatial data.

Choose Structure → GeoServer from the menu bar to visit the
GeoServer configuration page again. Select Layers and click Add to
add your new layer.

Type a suitable layer title.

Select the layer type. We choose PostGIS Field for advanced
geospatial operations and geodata storage.
As source select your created content type which will be associated
with your new layer.
Make the checkmark Provide an OpenLayers WFS layer within the
OpenLayers section.
Finish configuration by click on Save.
You can now also access the geospatial fields of your content type via
WFS or WMS with other applications (e.g. with QGis).

Congratulations! Your new GeoServer layer was added to GeoServer.

Configuring OpenLayers to activate your GeoServer layer in a

map

OpenLayers is used to display your new layer on a map. You will now
associate your GeoServer layer with your OpenLayers map.

Choose Structure → OpenLayers from the menu bar to visit the

OpenLayers maps configuration page.
Look for frontmap - a pre-generated, default map - and select Edit on
the right side.
frontmap’s configuration page appears as shown on the screenshot
below.
Select Layers & Styles in the left sidebar to add our newly created
layer to the frontmap.
Look for your created GeoServer layer (‘lakes’ in our example).
Make checkmarks for Enabled, Activated and In Switcher to activate
your new layer lakes in your map. Finish configuration by clicking on
Save at the bottom.
Adding geospatial content

After creating your content type and configuring GeoServer and

OpenLayers you can now add as many content elements of this type as
you want.

Choose Content from the menu bar to see all existing content
elements within your Cartaro installation.
Select Add content to add more content and choose your new content
type in the appearing window (not shown). In the configuration page of
your new content element (called node in Drupal language) make the
following settings:

1. Type a name
2. You can draw the geometry for your content element. Choose the
draw symbol on the upper right corner of the map. Note that tool
tips are shown when you hover the toolbar icons. Click on the
map to create a new geometry. Finish the drawing with double
click.
3. Save your geometry.

Only one geometry per content element can be drawn in our example
configuration. Create additional content elements to add more
polygons.
You should now see your new content element.
To view your new content element on the front map, click on the
house icon in the upper left corner.

Congratulations, you have just finished the quickstart tutorial. Your

first content element is now ready. To add more content elements
simply perform the steps of this section again.

Things to try
  Use the Layer Assistant to include external layers (see Structure
→ Open Layers → Layers → Add using assistant).
 Change the default map behaviours and build your own map.
 Try different geometry types and build more complex content
types.

A project by - spatial web.

Documentation
Using Drupal users and roles in GeoServer
The core idea of Cartaro is the closest possible integration of geodata
with other content in a single software stack. This aspect also
extends to the common management of users, roles and their
permissions, meaning you should be able to apply the same security
mechanisms and permissions for spatial and non-spatial content.
Within Cartaro the permissions for non-spatial content are handled by
Drupal. GeoServer, on the other hand, is responsible to deliver
optionally protected geospatial data to the web either through web
services (OWS) or through a number of downloadable file formats.

A GeoServer extension is provided in order to use Drupal as user and

role provider for GeoServer allowing Cartaro to forward Drupal
authorizations to GeoServer. This means you can set up a protected
geo web service with GeoServer that is automatically available to a
user after login into the Drupal site.

Further the same GeoServer provided service is available outside of

your Drupal site too, e.g. in a Desktop GIS connecting to GeoServer
directly. The usual authentication mechanisms as defined by the OGC
and implemented by GeoServer apply but do respect any permissions
set in Drupal (those are merged with the permissions you set in
GeoServer).
Even though setting GeoServer up this way is optional we do strongly
recommend doing so as it automates user/permission synchronization
which is an error prone process if done by hand.

Installing the GeoServer extension

Be sure to met the GeoServer prerequisites referred in the Cartaro
installation related with the JVM startup parameters and the session
timeout of GeoServer. A Drupal/PostGIS datasource (store) and its
workspace should exist before. These should have been created
automatically in a normal Cartaro installation.

The GeoServer extension is provided as a JAR file. The geoserver-sec-

drupal-7.x-x.x.jar version should match the Cartaro version. For
example, for cartaro-7.x-1.0 we will use geoserver-sec-drupal-7.x-1.0.jar
version. It needs to be placed in GeoServer folder geoserver/WEB-INF/lib/.
In case you use Tomcat to run GeoServer the path will be similar to
/var/lib/tomcat7/webapps/geoserver/WEB-INF/lib/.The geoserver-sec-drupal-7.x-
x.x.jar file owner and group must be set to Tomcat.

A classpath modification is used to override GeoServer's default

implementation. Open WEB-INF/web.xml and append
classpath*:/applicationSecurityContextOverride.xml to the
contextConfigLocation context parameter. This parameter sets where
Spring (GeoServer's authentication and access-control framework)
looks for implementations of classes. The later a configuration is read,
the more prioritized it is. Restart GeoServer so that it picks up the new
classes.

<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath*:/applicationContext.xml
classpath*:/applicationSecurityContext.xml
classpath*:/applicationSecurityContextOverride.xml</param-value>
</context-param>

Adding a Drupal Role Service

A Role Service is a source of roles or granted authorities for users and
groups. At any given time only a single role service may be active. The
active role service is used by User-Group Services when loading user
information to determine what roles to grant to a user.

As we want Drupal as a role provider for Geoserver, we need to add a

new role service of type Drupal. First, log into GeoServer using a user
with ADMIN role. In Security → Users, Groups, Roles → Role Services
click on Add new.
Choose a Role Service of type Drupal and set any name for it. Only one
such service is enough for any number of bound Drupal instances.

Finally make sure GeoServer does actually use the new service by
selecting it in GeoServer's global security settings.

Binding Drupal instances

Each Drupal instance whose users and roles should be available in
GeoServer needs to be added, too. To do so add an Authentication
Provider of type Drupal by clicking Add new in Security →
Authentication → Authentication Providers.
Choose any name for your Drupal instance and enter the connection
parameters for its database. The user you set here needs to be able to
read users and roles from the Drupal database. GeoServer will use it to
verify credentials and to read the roles for each authenticated user. If
GeoServer is shared by multiple Cartaro instances it is necessary to
check the Usernames are prefixed option to make Drupal instances
distinguishable in GeoServer.
Each Drupal instance needs its own User-Group Service. A User-Group
Service is a source of information for users, passwords, and group
affiliation. Add a User-Group Service clicking Add new in Security »
Users, Groups, Roles » User Group Services.

The name of the new User-Group Service should be the same that the
Workspace name that you choose when installing Cartaro. The
database credentials should be the same as used for the
Authentication Provider. Password Encryption can be set as plain text
since Drupal hashes passwords itself and Password policy can be set
as default. More info about password management inside GeoServer
can be found in GeoServer documentation.
Activate the authentication provider by moving it into the list of active
providers (Security → Authentication → Authentication Providers).

GeoServer will now acquire a database connection to your Drupal

instance and accept Drupal users for login thereafter.

Login into GeoServer

As long as you are using your browser to access Cartaro there is no
need to bother about logging into GeoServer. Cartaro will take care
that you are logged into GeoServer as well when logging into Cartaro
which allows access to all maps where your user has been granted by
the permission settings within Drupal.

Simply use the same user name and password as for logging into
Cartaro when accessing GeoServer's web services from a third-party
application. This applies in case you want to access GeoServer from a
desktop GIS for feature editing over WFS for example.
Note that you need to prepend your Drupal user name with Cartaro's
workspace if, and only if, your GeoServer is shared by multiple Cartaro
instances. For example if the GeoServer workspace used by Cartaro is
called forestry and your Drupal user is pat, your desktop GIS would
need to use forestry_pat as user name. Your password is unaltered.
Prefixing user names and roles in GeoServer provides that the Cartaro
instances are distinguishable in GeoServer in such case.

See geoserver-sec-drupal's readme for more detailed instructions.

« Back to Documentation index

Documentation
Store Geospatial Data
A field type called Geospatial Data is available in Cartaro and can be
used to define custom content types. Those fields can hold map
features of common types and contain an unlimited number of
features, each. You would define your content structure as usual but
also add Geospatial Data fields.
You can choose to either provide or view your data as WKT or on a
map. WKT is a simple text base format to specify spatial data. An
example of using a map for editing with point, line and area features
follows.

Documentation
Provide Geo Web Services
The tight integration of Cartaro with GeoServer allows you to publish
your geospatial data in a multitude of data formats and web services.
As soon as content types with geospatial data fields have been
created, you will be able to add layers to your GeoServer through
Cartaro. Creating your own GeoServer styles (SLD format) allows for
visual customization of GeoServer layers.
Creating new Geoserver layers from Cartaro
Based on the geodata in Drupal, we can create now GeoServer layers
that will be provided via WMS or WFS.

Go to Structure → GeoServer from the menu bar to visit the GeoServer

configuration page. Select Layers and click Add to add your new layer.
Type a layer title and description.
Select PostGIS Field as Layer type and your spatially-enabled content
type as Source. If you have created a Geoserver style though
Structure → GeoServer, it would be selectable here.
Within the OpenLayers section, is it possible to have this layer
automatically available in the layer list of the OpenLayers module. It
can be requested to GeoServer from the Openlayers client inside
Drupal through WFS, tiled WMS or untiled WMS protocols.

In the layer specifics section there is the actual layer definition that
will be created from GeoServer as a view performed over the Drupal
database. This view can be modified to fit your needs. The rules
defined at the end of the view definition allows WFS-T operations over
the layer.

Finish configuration by clicking on Save.

A project by x web.

Documentation
Visualize Geospatial Data
Custom maps can be configured using the OpenLayers module to
visualize geospatial data. This article will describe how to display your
spatial features on a map and how to build custom maps. You can
either display single features on separate pages or display collection
of spatial features on a central map as shown below.

Single Feature
The spatial features from a node can be displayed in numerous ways.
By default they will be visualized on a map. To change the display
settings go to Structures → Content types and click on manage display
of the content type you want to edit. Select the desired format and
optionally change the display settings by clicking on the button on the
right.

Feature Collection
Before you can display a collection of spatial features, you need to
create a GeoServer layer that contains those features. Go to
Structures → GeoServer → Layers and click on Edit of the respective
layer. Depending on your needs, enable one of the check boxes in the
OpenLayers form section.
The GeoServer layer is now available to the OpenLayers map
configuration. Go to Structures → OpenLayers → Maps and edit or

create a map. You can enable your layer from the list in the overlay
layers section that appears after clicking the Layers & Styles tab.
Styling can be provided using SLD files as shown in this example to
render railways and bridges differently. More information can be found
in the documentation of the OpenLayers module or the symbolization
howto.
Information Popups
Additional data can be provided for features using popups so that the
data is displayed as soon as a feature is clicked. Even though Cartaro
presents sensible information by default you might want to customize
the displayed data. To do it, open Structure → GeoServer and edit the
layer in question. Modify the SQL query so that a column name provides
the popup's title and a column description its main content. Also enable
and configure the Pop Up for Features behaviour in the OpenLayers
map settings.
 Documentation
Displaying maps within other content
Once you have configured a map in Cartaro you surely want to display
it in appropriately. You could use the Frontmap module if your site is
very map-centric but integrating maps within other content is often
preferable.

Setting up the map

Let's take a news article as example in which you want to have
textual content accompanied by maps. Firstly, configure your map as
shown in Getting Started with extensive detail. Note though, that the
name of the map does not matter so calling it frontmap is not
necessary.
Mind to enable all layers that you wish to display in the map
configuration. You should check out the list of Behaviours offered
there, too.

Enable maps in content

Drupal offers
settings for
various

transformation steps for content that allow to prepare a suitable

presentation. We'll use this mechanism to integrate maps in the article
this way.

Navigate to Configuration → Content authoring → Text formats and opt

to configure the format called Plain text.

Tick OpenLayers Filters in the list of filters and drag the items in the
processing order section around so that OpenLayers Filters comes
last. This allows Drupal to enhance your content (adding links for
example) and insert maps lastly so that other filters don't interfere
with map rendering.
Embedding maps
It's finally time to add content with maps or add maps to existing
content. Navigate to Content, then Add content or edit.

Whenever you type [openlayers your_map_name] the text format just

configured will take care to insert the map with the given name. Make
sure to choose the correct text format from the drop-down below the
text field. A hint about inserting maps will be display just below the
drop-down as shown in the screenshot.
The visual appearance of the maps will depend on your map
configuration, obviously. The first map in our example looks as shown
below.
 Documentation
Print Geospatial Data
A commonly desired functionality is the export of geospatial data as a
map. While for screen display a screenshot may be sufficient, higher
standards exist for print output. To meet these needs, Cartaro
provides a print function for OpenLayers maps. This is implemented
with the last version of MapFish Print, a server side component.
Because it requires additional software on the server, it is disabled by
default.
MapFish Print is written in Java and executed in a servlet container
such as Apache Tomcat. The installation and configuration of MapFish
Print is already documented and will not be further described here.

Once MapFish Print runs on the server, the OpenLayers Print module
can be activated and configured by going to Structure → OpenLayers
→ Print (see screenshot above). Afterwards enable the OpenLayers
Print behavior for desired maps and a print button should appear in the
lower right corner of the map.
 Documentation
How to protect your data
In an GIS environment it is often needed to protect the data provided
by the map server, restricting some clients to certain regions or
certain kinds of vector/raster data. As a consequence, clients must
authenticate themselves to have access to protected resources.

Drupal has fine-grained built-in protection for content types. The same
protection must apply to the geodata within Cartaro, but with Cartaro,
data can be accessed not only through the Drupal GUI. With its
integration with GeoServer, Cartaro can expose OGC webservices that
are accessed through direct HTTP requests according to the OGC
standards.

When accessing webservices with maps within Cartaro, stateful

authentication is shared between Drupal and GeoServer by means of a
commonly used cookie. Access to the OGC services is possible from
other clients, e.g. desktop GIS. As this access is stateless, we have to
make sure that data are also protected.

Step by step HowTo

Let's start creating a spatially-enabled content type. Drupal content
are naturally stored and shown in nodes. Within Cartaro, the
GeoServer module allows grouping nodes in layers that will be
delivered by GeoServer. Based on the geodata in Drupal stored in our
new content type, we can create now a layer that will be provided via
WMS or WFS.
This new layer will be automatically available in GeoServer, so their
access rules can be set as in any normal layer through the GeoServer
GUI. Anyway, to simplify data security management and avoid
mistakes, all access rules can be defined inside Cartaro. In the Cartaro
People → Permissions page, node content type permissions can be set
as usual but, additionally, under the Geoserver permissions group,
layer permissions can also be defined.

On layer creation, the default permissions are taken from the content

type permissions or for the Nodetype access if this module is

activated.

Layer permissions in Drupal will be promoted to GeoServer's security

settings. In this way, the same access rules will be applied to a layer
accessed directly in the Drupal GUI or though an OGC service from
GeoServer.
This permission synchronization only works if the GeoServer extension
to share users and roles with Drupal is installed.

A transactional Web Feature Service (WFS-T) allows creation, deletion,

and updating of features. Data may be written by means of WFS-T with
write privileges defined in Drupal being applied.

GeoServer also supports access control at the service level. There are
two main categories of services in GeoServer: OWS services, such as
WMS and WFS, and RESTful services. Service access rules can be
defined using the Geoserver GUI.

Usage of protected service from other clients

than Drupal
Protected layers can be also loaded from other clients, e.g. desktop
GIS though OGC services. In the image, a protected layer is accessed
using QGis asking for the required authentication.
A project web.