Installing Lizmap Web Client on Linux Debian or Ubuntu

Note

If you want to quickly install and test Lizmap Web Client in a few steps, you can follow those instructions using Docker and Docker-Compose.

Note

In Debian distributions, you can work as administrator (log in with root), without using sudo on contrary to Ubuntu.

Generic Server Configuration with Nginx server

This documentation provides an example for configuring a server with the Debian 9 distribution. We assume you have base system installed and updated.

Warning

This page does not describe how to secure your Nginx server. It’s just for a demonstration.

Configure Locales

For simplicity, it is interesting to configure the server with UTF-8 default encoding.

# configure locales
locale-gen fr_FR.UTF-8 #replace fr with your language
dpkg-reconfigure locales
# define your timezone [useful for logs]
dpkg-reconfigure tzdata
apt install ntp ntpdate

Note

It is also necessary configure the other software so that they are using this default encoding if this is not the case.

Nginx Server Configuration

This documentation provides an example for configuring a server with the Debian 9 distribution. We assume you have base system installed and updated.

Warning

This page does not describe how to secure your Nginx server. It’s just for a demonstration.

Installing necessary packages

Warning

Lizmap web client is based on Jelix 1.6. You must install at least the 5.6 version of PHP. The dom, simplexml, pcre, session, tokenizer and spl extensions are required (they are generally turned on in a standard PHP 5.6/7.x installation)

sudo su # only necessary if you are not logged in as root
apt update # update packages list
apt-get install curl openssl libssl1.1 nginx-full nginx nginx-common

On debian 10, install these packages:

apt-get install php7.3-fpm php7.3-cli php7.3-bz2 php7.3-curl php7.3-gd php7.3-intl php7.3-json php7.3-mbstring php7.3-pgsql php7.3-sqlite3 php7.3-xml php7.3-ldap

On Ubuntu 18.04 or later, install these packages:

apt-get install php7.3-fpm php7.3-cli php7.3-bz2 php7.3-curl php7.3-gd php7.3-intl php7.3-json php7.3-mbstring php7.3-pgsql php7.3-sqlite3 php7.3-xml php7.3-ldap

Web configuration

Create a new file /etc/nginx/sites-available/lizmap.conf:

server {
    listen 80;

    server_name localhost;
    root /var/www/html/lizmap;
    index index.php index.html index.htm;

    # compression setting
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 5;
    gzip_min_length 100;
    gzip_http_version 1.1;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript text/json;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ [^/]\.php(/|$) {
       fastcgi_split_path_info ^(.+\.php)(/.*)$;
       set $path_info $fastcgi_path_info; # because of bug http://trac.nginx.org/nginx/ticket/321
       try_files $fastcgi_script_name =404;
       include fastcgi_params;

       fastcgi_index index.php;
       fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
       fastcgi_param PATH_INFO $path_info;
       fastcgi_param PATH_TRANSLATED $document_root$path_info;
       fastcgi_pass unix:/var/run/php/php7.3-fpm.sock;
       fastcgi_param SERVER_NAME $http_host;
    }
}

You should declare the lizmap.local domain name somewhere (in your /etc/hosts, or into your DNS..), or replace it by your own domain name.

Enable the virtual host you just created:

ln -s /etc/nginx/sites-available/lizmap.conf /etc/nginx/sites-enabled/lizmap.conf

Restart Nginx

You must restart the Nginx server to validate the configuration.

service nginx restart

Apache Server configuration

This documentation provides an example for configuring a server with the Debian 10 distribution. We assume you have base system installed and updated.

Warning

This page does not describe how to secure your Apache server. It’s just for a demonstration.

Installing necessary packages

Firstly update the packages list, then install these packages:

sudo su # only necessary if you are not logged in as root
apt update
apt-get install xauth htop curl apache2 libapache2-mod-fcgid
apt-get install libapache2-mod-php7.3 php7.3-cgi php7.3-gd php7.3-sqlite php7.3-curl php7.3-xmlrpc php7.3-xml python-simplejson software-properties-common

PHP 7.3 configuration

In this example, we use Apache mpm-worker. So we must manually configure the activation of PHP 7.3.

# Create the configuration file
nano /etc/apache2/conf-available/php.conf
# Copy the following text in it
<Directory /usr/share>
   AddHandler fcgid-script .php
   FCGIWrapper /usr/lib/cgi-bin/php7.3 .php
   Options ExecCGI FollowSymlinks Indexes
</Directory>

<Files ~ (\.php)>
   AddHandler fcgid-script .php
   FCGIWrapper /usr/lib/cgi-bin/php7.3 .php
   Options +ExecCGI
   allow from all
</Files>

Enable the configuration with the following command line:

a2enconf php

Web configuration

mpm-worker configuration

We modify the Apache configuration file to adapt the options to mpm_worker server configuration.

nano /etc/apache2/apache2.conf
<IfModule mpm_worker_module>
StartServers       4
MinSpareThreads    25
MaxSpareThreads    100
ThreadLimit          64
ThreadsPerChild      25
MaxClients        150
MaxRequestsPerChild   0
</IfModule>

mod_fcgid configuration

QGIS Server runs with the FastCGI protocole (a.k.a. fcgi). We must therefore configure the Apache mod_fcgid to suit to the server capabilities.

# Open the mod_fcgid configuration file
 nano /etc/apache2/mods-enabled/fcgid.conf
 # Paste the following content and adapt it
 <IfModule mod_fcgid.c>
    AddHandler    fcgid-script .fcgi
    FcgidConnectTimeout 300
    FcgidIOTimeout 300
    FcgidMaxProcessesPerClass 50
    FcgidMinProcessesPerClass 20
    FcgidMaxRequestsPerProcess 500
    IdleTimeout   300
    BusyTimeout   300
 </IfModule>

Setting the compression

nano /etc/apache2/conf-available/mod_deflate.conf
# Add the bellow text in the file
<Location />
   # Insert filter
   SetOutputFilter DEFLATE
   # Netscape 4.x encounters some problems ...
   BrowserMatch ^Mozilla/4 gzip-only-text/html
   # Netscape 4.06-4.08 encounter even more problems
   BrowserMatch ^Mozilla/4\.0[678] no-gzip
   # MSIE pretends it is Netscape, but all is well
   BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
   # Do not compress images
   SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip dont-vary
   # Ensure that proxy servers deliver the right content
   Header append Vary User-Agent env=!dont-vary
</Location>

Restart Apache

You must restart the Apache server to validate the configuration.

service apache2 restart
# or
systemctl restart apache2

Enable geolocation

The automatic geolocation provided by Lizmap relies on Google services. To enable it, your webGIS must be placed under a secure protocol, like HTTPS. See for more details:

https://sites.google.com/a/chromium.org/dev/Home/chromium-security/deprecating-powerful-features-on-insecure-origins

https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-apache-in-ubuntu-16-04

Create directories for data

QGIS files and other cache files will be stored into these directories.

 mkdir /home/data
 mkdir /home/data/cache/
# optional
 mkdir /home/data/ftp
 mkdir /home/data/ftp/template/
 mkdir /home/data/ftp/template/qgis

Spatial Database: PostgreSQL

Note

This section is optional. Please read PostgreSQL.

PostgreSQL and PostGIS can be very useful to manage spatial data centralized manner on the server.

Install

# Install packages
apt-get install postgresql postgresql-contrib postgis pgtune

# A cluster is created in order to specify the storage directory
mkdir /home/data/postgresql
service postgresql stop
pg_dropcluster --stop 9.6 main
chown postgres:postgres /home/data/postgresql
pg_createcluster 9.6 main -d /home/data/postgresql --locale fr_FR.UTF8 -p 5678 --start

# Creating a "superuser" user
su - postgres
createuser myuser --superuser
# Modifying passwords
psql
ALTER USER postgres WITH ENCRYPTED PASSWORD '************';
ALTER USER myuser WITH ENCRYPTED PASSWORD '************';
\q
exit

Adapting the PostgreSQL configuration

We will use pgtune, an utility program that can automatically generate a PostgreSQL configuration file adapted to the properties of the server (memory, processors, etc.)

https://pgtune.leopard.in.ua/

# PostgreSQL Tuning with pgtune
pgtune -i /etc/postgresql/9.6/main/postgresql.conf -o /etc/postgresql/9.6/main/postgresql.conf.pgtune --type Web
cp /etc/postgresql/9.6/main/postgresql.conf /etc/postgresql/9.6/main/postgresql.conf.backup
cp /etc/postgresql/9.6/main/postgresql.conf.pgtune /etc/postgresql/9.6/main/postgresql.conf
nano /etc/postgresql/9.6/main/postgresql.conf
# Restart to check any problems
service postgresql restart
# If error messages, increase the linux kernel configuration variables
echo "kernel.shmall = 4294967296" >> /etc/sysctl.conf # to increase shred buffer param in kernel
echo "kernel.shmmax = 4294967296" >> /etc/sysctl.conf
echo 4294967296 > /proc/sys/kernel/shmall
echo 4294967296 > /proc/sys/kernel/shmmax
sysctl -a | sort | grep shm
# Restart PostgreSQL
service postgresql restart

For installing Lizmap tables into the PostgreSQL database (instead of SqLite by default), you can continue until the next section below when you need to edit the file lizmap/var/config/profiles.ini.php.

FTP Server: pure-ftpd

Note

This section is optional, you can setup your own way of transferring data from QGIS GIS technicians to the Lizmap server.

Install

apt-get install pure-ftpd pure-ftpd-common

Configure

# Creating an empty shell for users
ln /bin/false /bin/ftponly
# Configuring FTP server
echo "/bin/ftponly" >> /etc/shells
# Each user is locked in his home
echo "yes" > /etc/pure-ftpd/conf/ChrootEveryone
# Allow to use secure FTP over SSL
echo "1" > /etc/pure-ftpd/conf/TLS
# Configure the properties of directories and files created by users
echo "133 022" > /etc/pure-ftpd/conf/Umask
# The port range for passive mode (opening outwards)
echo "5400 5600" > /etc/pure-ftpd/conf/PassivePortRange
# Creating an SSL certificate for FTP
openssl req -x509 -nodes -newkey rsa:1024 -keyout /etc/ssl/private/pure-ftpd.pem -out /etc/ssl/private/pure-ftpd.pem
chmod 400 /etc/ssl/private/pure-ftpd.pem
# Restart FTP server
service pure-ftpd restart

Creating a user account

# Creating a user account
MYUSER=demo
useradd -g client -d /home/data/ftp/$MYUSER -s /bin/ftponly -m $MYUSER -k /home/data/ftp/template/
passwd $MYUSER
# Fix the user's FTP root
chmod a-w /home/data/ftp/$MYUSER
# Creating empty directories that will be the future Lizmap Web Client directories
mkdir /home/data/ftp/$MYUSER/qgis/rep1 && chown $MYUSER:client /home/data/ftp/$MYUSER/qgis/rep1
mkdir /home/data/ftp/$MYUSER/qgis/rep2 && chown $MYUSER:client /home/data/ftp/$MYUSER/qgis/rep2
mkdir /home/data/ftp/$MYUSER/qgis/rep3 && chown $MYUSER:client /home/data/ftp/$MYUSER/qgis/rep3
mkdir /home/data/ftp/$MYUSER/qgis/rep4 && chown $MYUSER:client /home/data/ftp/$MYUSER/qgis/rep4
mkdir /home/data/ftp/$MYUSER/qgis/rep5 && chown $MYUSER:client /home/data/ftp/$MYUSER/qgis/rep5
# Create a directory to store the cached server
mkdir /home/data/cache/$MYUSER
chmod 700 /home/data/cache/$MYUSER -R
chown www-data:www-data /home/data/cache/$MYUSER -R

Installing sources of Lizmap Web Client

Retrieve the latest available stable version from our Github release page.

Warning

Do not use the automatic ZIP file created by GitHub on the website. Only use ZIP attached to a release.

# Options
# Check the latest version available, maybe it's not 3.5.1 anymore
# https://github.com/3liz/lizmap-web-client/releases
VERSION=3.5.1
# chose location where download your zip (e.g. /var/www or your home)
LOCATION=/var/www
# Archive recovery with wget
cd $LOCATION
wget https://github.com/3liz/lizmap-web-client/releases/download/$VERSION/lizmap-web-client-$VERSION.zip
# Unzip archive
unzip $VERSION.zip

# virtual link for http://localhost/lizmap/
ln -s $LOCATION/lizmap-web-client-$VERSION/lizmap/www/ /var/www/html/lizmap
# Remove archive
rm $VERSION.zip

Configure Lizmap with the database support

Lizmap needs a database to store its own data and to access to data used in your Qgis projects, with its editing tool.

Create profiles.ini.php into lizmap/var/config by copying profiles.ini.php.dist.

cd lizmap/var/config
cp profiles.ini.php.dist profiles.ini.php
cd ../../..

PostgreSQL

For the editing of PostGIS layers in Web Client Lizmap operate, install PostgreSQL support for PHP. No configuration file need to be edited to edit PostgreSQL layer. You must only check that the Lizmap server can access the database with credentials which are stored in the QGIS project (or with a PostgreSQL service file).

sudo apt-get install php7.3-pgsql
sudo service nginx restart

For Lizmap logs, users and groups, it can be either stored in SqLite or PostgreSQL. To store these information in PostgreSQL, follow these instructions.

Into a fresh copy of lizmap/var/config/profiles.ini.php, you should have:

[jdb:jauth]
driver=sqlite3
database="var:db/jauth.db"

[jdb:lizlog]
driver=sqlite3
database="var:db/logs.db"

This is the configuration by default to use Sqlite. You should change these sections to use Postgresql, and indicate several parameters to access to your Postgresql database:

[jdb:jauth]
driver=pgsql
host=localhost
port=5432
database="your_database"
user=my_login
password=my_password
search_path=public

[jdb:lizlog]
driver=pgsql
host=localhost
port=5432
database="your_database"
user=my_login
password=my_password
search_path=public

You can use a specific schema to store lizmap tables. And you may want that lizmap could access to other schema. You then have to set search_path correctly. Example:

search_path=lizmap,my_schema,public

If you have setup a service file for postgresql onto your server, you may want to indicate a postgresql service instead of indicating login, password and so on. Use then the service parameter:

[jdb:jauth]
driver=pgsql
service=my_service
database="your_database"
search_path=lizmap,public

[jdb:lizlog]
driver=pgsql
service=my_service
database="your_database"
search_path=lizmap,public

Spatialite

Enable Spatialite extension

To use editing on layers spatialite,you have to add the spatialite extension in PHP. You can follow these instructions to do so: http://www.gaia-gis.it/gaia-sins/spatialite-cookbook-fr/html/php.html

Lizmap Web Client tests whether the spatialite support is enabled in PHP. If it is not, then spatialite layers will not be used in the editing tool. You can always use PostgreSQL data for editing.

Give the appropriate rights to the directory containing Spatialite databases

So that Lizmap Web Client can modify the data contained in databases Spatialite, we must ensure that the webserver user (www-data) has well write access to the directory containing each Spatialite file

For example, if a directory contains a QGIS project, which uses a Spatialite database placed in a db directory at the same level as the QGIS project:

/path/to/a/lizmap_directory
|--- mon_projet.qgs
|--- bdd
   |--- my_spatialite_file.sqlite

So you have to give the rights in this way:

chown :www-data /path/to/a/lizmap_directory -R
chmod 775 /path/to/a/lizmap_directory -R

Note

So if you want to install Lizmap to provide access to multiple map publishers, you should tell them to always create a db directory at the same level as the QGIS projects in the Lizmap Web Client directory. This will facilitate the admin work that just have to change the rights of this unique directory.

Configuring Lizmap and launching the installer

Give the appropriate rights to directories and files

Set rights for Nginx/Apache, so PHP scripts could write some temporary files or do changes.

cd /var/www/lizmap-web-client-$VERSION/
lizmap/install/set_rights.sh www-data www-data
chown :www-data lizmap/install/qgis/edition/ -R
chmod 775 lizmap/install/qgis/edition/ -R

Setup configuration

Create lizmapConfig.ini.php, localconfig.ini.php and edit them to set parameters specific to your installation. You can modify lizmapConfig.ini.php to set the url of qgis map server and other things.

cd lizmap/var/config
cp lizmapConfig.ini.php.dist lizmapConfig.ini.php
cp localconfig.ini.php.dist localconfig.ini.php
cd ../../..

In case you want to enable the demo repositories, just add to localconfig.ini.php the following:

[modules]
lizmap.installparam=demo

Launching the installer

After creating configuration files, you can launch the installer

php lizmap/install/installer.php

It will finished the installation, and will create all SQL tables needed by Lizmap.

First test

For testing launch: http://localhost/lizmap in your browser.

In case you get a 500 - internal server error, run again:

cd /var/www/lizmap-web-client-$VERSION/
lizmap/install/set_rights.sh www-data www-data

Note

Replace localhost with the address or IP number of your server.

In the administration panel, you should check the QGIS server version and the WMS server URL with the URL of QGIS Server.

Warning

Before trying to have a QGIS project working in Lizmap, you must have the communication between QGIS Server and Lizmap Web Client working properly. Versions about QGIS Server plugins must be visible from the administration interface. Please read Lizmap QGIS Server plugin.

If you didn’t install the demo, you can check that you have well installed Lizmap and configured QGIS Server within Lizmap by checking the qgis_server section in this URL: http://localhost/lizmap/index.php/view/app/metadata

{
    "qgis_server":{
        "test":"OK",
        "mime_type":"text\/xml; charset=utf-8"
    }
}

Lizmap is accessible, without further configurations, also as WMS and WFS server from a browser:

http://localhost/lizmap/index.php/lizmap/service/?repository=montpellier&project=montpellier&VERSION=1.3.0&SERVICE=WMS&REQUEST=GetCapabilities

http://localhost/lizmap/index.php/lizmap/service/?repository=montpellier&project=montpellier&SERVICE=WFS&REQUEST=GetCapabilities

and from QGIS:

http://localhost/lizmap/index.php/lizmap/service/?repository=montpellier&project=montpellier&VERSION=1.3.0&

http://localhost/lizmap/index.php/lizmap/service/?repository=montpellier&project=montpellier&

Note

Access to the WMS and WFS servers can be limited by assigning privileges to specific repositories, see the administration section.

Lizmap modules

Previously, we explained how we could add QGIS Server plugins to add more features to QGIS Server. Now that we have Lizmap Web Client up and running, we can add some Lizmap modules to add again some features.

The list is available in the Lizmap introduction. On their GitHub repository, their is usually their install instructions. You should follow them. However here are the main instructions to install a module.

Installing modules with Composer

You can install modules with Composer, the package manager for PHP. Of course it is possible only if the author of the module has created a package of his module. A such package has a name, for example lizmap/lizmap-pgmetadata-module`. The documentation of the module should indicate it.

You must install Composer. See instructions on its web site http://getcomposer.org.

You must create a composer.json file into lizmap/my-packages/ by copying the composer.json.dist from this directory. And launching a first time Compose

cp -n lizmap/my-packages/composer.json.dist lizmap/my-packages/composer.json
composer install --working-dir=lizmap/my-packages

Then you can install the package of the module

composer require --working-dir=lizmap/my-packages "lizmap/lizmap-pgmetadata-module"

If you want to install a new version of the module, just execute:

composer update --working-dir=lizmap/my-packages

Read the documentation of the module to know if there are additional steps to configure it.

To finish the installation, run again the installer of Lizmap:

php lizmap/install/installer.php
lizmap/install/clean_vartmp.sh
lizmap/install/set_rights.sh

installing modules without Composer

To install a module without Composer, retrieve the zip file of the module.

  • Extract the module into lizmap/lizmap-modules/. For instance, for the module PgMetadata :
$ ls -hl lizmap/lizmap-modules/pgmetadata/
total 44K
drwxrwxr-x 2 etienne etienne 4,0K nov.  17 12:38 classes
drwxrwxr-x 2 etienne etienne 4,0K nov.   4 12:50 controllers
drwxrwxr-x 2 etienne etienne 4,0K nov.   4 10:09 daos
-rw-rw-r-- 1 etienne etienne  146 nov.   4 10:38 events.xml
drwxrwxr-x 2 etienne etienne 4,0K nov.   4 10:09 forms
drwxrwxr-x 2 etienne etienne 4,0K nov.   4 12:50 install
drwxrwxr-x 4 etienne etienne 4,0K nov.   4 10:09 locales
-rw-rw-r-- 1 etienne etienne  789 nov.  19 16:02 module.xml
drwxrwxr-x 2 etienne etienne 4,0K nov.   4 10:09 templates
-rw-rw-r-- 1 etienne etienne  106 nov.   4 10:39 urls.xml
drwxrwxr-x 2 etienne etienne 4,0K nov.  17 12:38 www
  • Edit the lizmap/var/config/localconfig.ini.php, in the modules section, add a new line for the given module (check the documentation of the module to setup the correct values):
[modules]
pgmetadata.access=2
  • Read the documentation of the module to know if there are additional steps to configure it.
  • Run the installation :
php lizmap/install/installer.php
lizmap/install/clean_vartmp.sh
lizmap/install/set_rights.sh