Details of the configuration of Mapbender3

Configuration steps

Following we describe the configuration steps of Mapbender3 a bit further. Configuring your Mapbender3 installation is made up of the following six steps:

  • Creating the database
  • Creating the database schema
  • Copying the bundles’ assets to the public web directory
  • Creating the “root” user
  • Inserting srs parameters (EPSG code definition)
  • Loading the applications of the mapbender.yml to your database

All can be done using the console utility provided by Symfony2, on which Mapbender3 framework is built upon. There’s a mayor caveat though you should understand, before continuing:

The console utility will write files in the app/cache and app/logs directories. These operations are made using the user permissions of whatever user you’re logged in with. This is also true for the app/db directory and the SQLite database within. When you open the application from within the browser, the server PHP process will try to access/write all these files with other permissions. So make sure you give the PHP process write access to these files. See last step below.

Notice: The following steps assume that you are in the directory above the app directory (notice that for git installation that means mapbender3/application/ else mapbender3/).

cd mapbender3/
or for git based installation
cd mapbender3/application

Adapting the configuration file

Database connection parameters are stored together with some more configuration parameters in the file app/config/parameters.yml. This file is using YAML syntax, so be aware that you can not use tabs for indenting. Be careful about this and use whitespaces instead.

Your database configuration in the parameters.yml file could look like this when you use PostgreSQL:

database_driver:   pdo_pgsql
database_host:     localhost
database_port:     5432
database_name:     mapbender3
database_path:
database_user:     postgres
database_password: secret

Further information is available in the chapter Configuring the database.

Creating the database

Symfony2 can attempt to create your database, this works of course only if the configured database user is allowed to. Call the console utility like this:

app/console doctrine:database:create

Creating the database schema

Symfony2 will create the database schema for you:

app/console doctrine:schema:create

Copying the bundles’ assets

Each bundle has it’s own assets - CSS files, JavaScript files, images and more - but these need to be copied into the public web folder:

app/console assets:install web

Alternatively, as a developer, you might want to use the symlink switch on that command to symlink instead of copy. This will make editing assets inside the bundle directories way easier.

app/console assets:install web --symlink --relative

Creating the administrative user

The first user - which has all privileges - must be created using the command:

app/console fom:user:resetroot

This will interactively ask all information needed and create the user in the database.

Alternatively, there is a silent mode you can use, if you want to use a script to install Mapbender3 and don’t want to be asked for all parameters:

app/console fom:user:resetroot --username="root" --password="root" --email="root@example.com" --silent

Inserting srs parameters

Inserting proj4 srs parameters into a database occurs using the command:

app/console doctrine:fixtures:load --fixtures=./mapbender/src/Mapbender/CoreBundle/DataFixtures/ORM/Epsg/ --append

Importing applications from mapbender.yml

Importing applications from mapbender.yml into a database occurs using the command:

app/console doctrine:fixtures:load --fixtures=./mapbender/src/Mapbender/CoreBundle/DataFixtures/ORM/Application/ --append

Configuration files

The basic configuration is done inside the app/config/parameters.yml file. A template is provided in the app/config/parameters.yml.dist file.

app/config/config.yml provides more parameters f.e. to configure portal functionality, owsproxy or provide an additional database.

parameters.yml

  • database: The parameters starting with database are the database connection details.
  • mailer: The mailer settings start with mailer. Use f.e. smtp or sendmail.
  • locale: You can choose a locale for your application (default is en, de is available). Check http://doc.mapbender3.org/en/book/translation.html to find out how to modify translations or how to add a new language.

Notice: You need a mailer for self-registration and reset password functionality.

If you use a proxy you have to add the proxy settings to parameters.yml at section OWSProxy Configuration.

This is how the configiration could look like:

# OWSProxy Configuration
    ows_proxy3_logging: false
    ows_proxy3_obfuscate_client_ip: true
    ows_proxy3_host: myproxy
    ows_proxy3_port: 8080
    ows_proxy3_connecttimeout: 60
    ows_proxy3_timeout: 90
    ows_proxy3_user: ~
    ows_proxy3_password: ~
    ows_proxy3_noproxy:
        - 192.168.1.123

config.yml

  • fom_user.selfregistration: To enable or disable self-registration of users, change the fom_user.selfregistration parameter. You have to define self_registration_groups, so that self-registered users are added to these groups automatically, when they register. They will get the rights that are assigned to these groups.
  • fom_user.reset_password: In the same way the possibility to reset passwords can be enabled or disabled.
  • framework.session.cookie_httponly: For HTTP-only session cookies, make sure the framework.session.cookie_httponly parameter is set to true.

Notice: You need a mailer for self-registration and reset password functionality (see parameters.yml).

mapbender.yml

You can configure an applications on two ways. In the mapbender.yml file or with the browser in the Mapbender3 backend.

  • The Mapbender Team provides an up-to-date mapbender.yml with demo applications. New elements with their parameters are added to this configuration in every new version (You can disable the applications by setting published: false or you can empty the mapbender.yml file)
  • applications that are defined in the mapbender.yml are not editable in the backend
  • you can import the applications to the database with the following app/console command
app/console doctrine:fixtures:load --fixtures=./mapbender/src/Mapbender/CoreBundle/DataFixtures/ORM/Application/ --append

Production- and Development environment and Caching: app.php and app_dev.php

Mapbender3 provides two environments: a production-environment for the general operation and a development-environment in which the application can be testet. This concept follows the “environments” in the Symfony framework.

The production-environment is called with the URL http://localhost/mapbender3/app.php, the development-environment with the URL http://localhost/mapbender3/app_dev.php. The call with app_dev.php is and should only be available from localhost.

There are differences in the behaviour of app.php and app_dev.php:

  • The cache-mechanism of the development-environment behaves different: Not all files are cached, so that the code-changes are directly visible. Therefore is the usage of the app_dev.php always slower that the production-environment.

    In detail, the development-environment of Mapbender3 does not cache the CSS, JavaScript and Translation files, among others.

    The production-environment caches all theses files and puts them into the app/cache folder.

  • The development-environment gives out error-messages and stack-traces out to the user-interface. The production-environment logs them into the file app/log/prod.log.

  • The development-environment shows the Symfony Profiler. This tool logs things, that are important for developers but should not be visible for common users.

    ../../../_images/symfony_profiler1.png

The directory app/cache contains the cache-files. It contains directories for each environment (prod and dev) but the mechanism of the dev-cache, as described, behaves different.

If changes of the Mapbender3 interface or the code are made, the cache-directory (app/cache) has to be cleared to see the changes in the application.

The following screenshots shows the location of the cache-directory in Mapbender3:

../../../_images/mapbender_cache_directories1.png

Logging in Mapbender3

The Log-Level is defined in the files config_dev.yml and config_prod.yml. These files are placed in the folder application/app/config/. The config-files are for the different environments (see production- and development environment).

For the development-environment (at the development on local systems) Mapbender3 is called with app_dev.php and therefore the file config_dev.yml is responsible. In the production-environment, where the app.php file is used, the configuration from config_prod.yml is applied.

Loglevel

Overall, 6 log-levels are used:

  • DEBUG (100): Detailed debug information.
  • INFO (200): Interesting events. Examples: User logs in, SQL logs.
  • NOTICE (250): Normal but significant events.
  • WARNING (300): Exceptional occurrences that are not errors. Examples: Use of deprecated APIs, poor use of an API, undesirable things that are not necessarily wrong.
  • ERROR (400): Runtime errors that do not require immediate action but should typically be logged and monitored.
  • CRITICAL (500): Critical conditions. Example: Application component unavailable, unexpected exception.
  • ALERT (550): Action must be taken immediately. Example: Entire website down, database unavailable, etc. This should trigger the SMS alerts and wake you up.
  • EMERGENCY (600): Emergency: system is unusable.

This description of the log-level is analog to the IETF Syslog Protocol.

config_dev.yml

You find the responsible part of the config_dev.yml in the section “monolog”:

monolog:
    handlers:
        main:
            type:  stream
            path:  %kernel.logs_dir%/%kernel.environment%.log
            level: debug
        firephp:
            type:  firephp
            level: info

Two “handler” are described: main und firephp.

  • main: The handler main is set to the log-level debug and streams all entries in a file which is defined unter path. This file is defined with variables which means that the file dev.log is placed under the folder application/app/logs/.
  • firephp: The handler firephp can communicate with an appropriate Extension of the web browser. The developer can therefore see the debug-messaged directly in the web browser without opening the log files.

These are the preferred settings for development tasks.

config_prod.yml

monolog:
    handlers:
        main:
            type:         fingers_crossed
            action_level: error
            handler:      nested
        nested:
            type:  stream
            path:  "%kernel.logs_dir%/%kernel.environment%.log"
            level: debug

This settings lead to a two-step logging. Here we have also two handlers: main and nested.

  • main: The main handler ist a type fingers-crossed and set to the error level. This means, the error is only active when an error occurs.

  • nested: The main-Handler calls the nested handler, which writes the entries into the prod.log file.

    Per default the handler is set to debug so that on an error also the debug-messages are written into the prod.log file.

    If you want to disable the debug-messages you can set here also the log-level error.

Further links: