Anatomy of a Lizmap instance: the components and how they fit together

What is a Lizmap instance at LizPack?

With LizPack Map, a Lizmap instance is a complete map portal, under your own name, installed and maintained for you. It is created in about four minutes from the customer area: you choose a name, that name becomes your subdomain, and all of the components are set up and connected to one another automatically, without any action on your part.

There is one essential point to keep in mind: LizPack did not write this software. Lizmap Web Client, QGIS Server, PostgreSQL and PostGIS are developed by their own communities. LizPack, an open source geospatial infrastructure, orchestrates them: it deploys them, configures them so that they can talk to each other, updates them and monitors them. This is exactly what the guide What LizPack does describes in detail.

An instance therefore contains six elements, which you will also find listed on the page for LizPack Map, our Lizmap hosting offer: Lizmap Web Client, QGIS Server, a PostgreSQL database with PostGIS, a tile cache, a subdomain and an HTTPS certificate. Each of these elements has a specific role, described in the sections below.

The six components of a Lizmap instance

On top of these come the tools you use to feed the instance: the online file manager, which lets you upload, organize and replace your projects and your data directly from the browser, and the free LizPack Publisher plugin, which sends a project and its data straight from QGIS Desktop.

Why so many pieces? Because each one does a single thing and does it well. Lizmap Web Client handles the interface and the access rights, but it does not know how to draw a map. QGIS Server draws the map, but it offers no interface to visitors. PostGIS stores and queries data, but it does not produce images. It is the combination of all of them that makes a portal. The benefit of a prepared instance is that the versions of these programs are chosen to be compatible with one another, and that the components are delivered already connected, subdomain and certificate included, before you even log in for the first time. Installing Lizmap yourself remains entirely possible: the software is open source and well documented. The difference lies in the time spent connecting everything together, and then in the time spent maintaining all of it over the months and years.

How a Lizmap instance displays a map

Here, in simplified form, is the path a map follows, from the QGIS project all the way to your visitor's screen. This is how Lizmap works in general: LizPack does not change it, it simply makes sure that every link in the chain is in place and working.

1. The project is prepared in QGIS Desktop. You put together the layers, the styles and the labels, then you configure the publication with the Lizmap plugin, just as you would for any Lizmap publication.
2. The project reaches the instance. You send it with LizPack Publisher or with the online file manager. The project file and its file-based data (GeoPackage, Shapefile, rasters) are placed on the instance; PostGIS layers, for their part, stay in the database.
3. The visitor opens the portal address. Their browser reaches your subdomain over HTTPS. Lizmap Web Client checks their access rights and shows them the list of maps, then the map they requested.
4. Lizmap requests the images from QGIS Server. For each view of the map, Lizmap forwards the request to QGIS Server, which opens the project, reads the data from the files or from PostGIS, applies the project styles and returns an image.
5. The tile cache avoids doing the same work twice. Pieces of the map that have already been computed can be served again directly, which speeds up the display of layers that rarely change.
6. Interactions follow the same path. Querying a feature, running a search, exporting data or editing online are all handled by Lizmap, with QGIS Server and PostGIS working behind it.

Because QGIS Server reads the QGIS project exactly as it is, the online map looks like the one on your own computer. A project that is slow to display in QGIS Desktop will also be slow online: the preparation work remains your responsibility.

The PostGIS database, the heart of live data

File-based layers are well suited to data that rarely changes. As soon as data is modified often, by several people or from the field, the PostGIS database of the instance takes over. It is delivered already connected to Lizmap and to QGIS Server: a PostGIS layer in the project is read every time the map is displayed, so it is always up to date.

The Basic and Pro plans include database storage linked to the instance. Starting with the Pro plan, you can connect to it directly from QGIS Desktop or pgAdmin, and LizPack Publisher lets you add tables from it as layers, import a layer into it and run a diagnosis on that layer. If you need more space or an independent database, dedicated PostgreSQL and PostGIS databases from 1 to 10 GB can be created separately and then connected to the instance.

It is also the database that provides the link with field data collection: with LizPack Field and the Pro plan, the observations entered in QField are written to PostGIS, and the Lizmap map that displays them is updated at every synchronization. The guide Synchronizing QField, PostGIS and Lizmap explains this circuit in detail.

What surrounds the instance: modules, team, monitoring

• Modules. From the Modules tab of the instance, you can add Lizmap modules such as dashboards or MapBuilder. Installation takes less than a minute, and the portal remains accessible the whole time.
• Team. The Pro plan lets you invite up to five collaborators. Permissions to view the maps, on the other hand, are set in the Lizmap administration.
• Themes. A theme from the marketplace can be copied to give your maps their own look.
• Updates. Updating Lizmap and QGIS Server is launched in one click. It is included starting with the Pro plan and costs 10 USD per component on the Free and Basic plans.
• Monitoring. The status of the services of each instance is checked continuously, and a broken link between the components is detected and repaired. The overall status of the platform is published on a public page.

What changes from one plan to another in a Lizmap instance

The six components are present in every instance. What varies from one plan to another is the way they are allocated: shared or dedicated, and with how much space. The table below uses the fallback prices published on the website; the Pricing page always shows the current values.

A shared QGIS Server serves the projects of several accounts: this is enough to discover Lizmap and to test a project. A dedicated QGIS Server serves only your instance, which prevents a heavy map from another account from slowing down yours. This is why a project that is meant to be viewed regularly belongs on at least a Basic plan.

The Pro plan adds two elements that change the way you work with the instance: a direct connection to the database from QGIS Desktop or pgAdmin, and included updates of Lizmap and QGIS Server. It also lets you invite up to five team members. The guide Understanding LizPack plans and quotas explains every line of the pricing grid.

From creating the instance to sharing the map

The four steps described on the LizPack Map page are enough to go from an empty account to a map online. Here is what each of them sets in motion inside the instance.

1. Create the instance. You choose a name, which becomes your subdomain. During the roughly four minutes that the creation takes, LizPack installs Lizmap Web Client, prepares QGIS Server in the chosen version, creates the PostGIS database, configures the tile cache and obtains the HTTPS certificate.
2. Prepare the project. In QGIS Desktop, you configure the project with the Lizmap plugin: visible layers, tools offered to visitors, scales, printing. This configuration travels with the project; it is what Lizmap reads when the map is opened.
3. Publish. LizPack Publisher validates the open project and then sends it along with its data. You can also send an entire folder from your computer, with its structure preserved, or go through the online file manager. Every operation of the plugin is recorded in a log, which can be copied in one click and attached to a request to support.
4. Share. The map is online. Access rights are set in the Lizmap administration: a public map, or a map restricted to certain accounts or to certain groups.

The guide Publishing a Lizmap map from QGIS walks through this process step by step, with the settings of the Lizmap plugin.

Projects and data that a Lizmap instance accepts

A LizPack Map instance serves ordinary QGIS projects. There is no format specific to LizPack: a project that works in a Lizmap installed somewhere else also works in an instance, and the reverse is true as well.

• The project. Any QGIS project configured with the Lizmap plugin in QGIS Desktop.
• File-based layers. GeoPackage, Shapefile and rasters, uploaded together with the project.
• PostGIS layers. The tables of the instance database, or of a dedicated database connected to the instance.
• External services. A WMS or WFS service, for example one published in GeoServer Cloud, is added to the QGIS project and then displayed in Lizmap like any other layer.
• The publishing plugin. LizPack Publisher requires QGIS 3.16 at a minimum and adds no library to your QGIS installation.

Lizmap modules are installed on a running instance, on Lizmap 3.9. The Modules tab flags any module that is not compatible with the version of your instance.

The life of an instance: space, alerts, expiration

An instance takes up space: the project files on one side, the database on the other. Each has its own quota, depending on the plan. For the database, LizPack warns you before it is full, and going over the quota never deletes anything: the database is stopped, not emptied. Dedicated databases send an email as soon as they reach 60% of their capacity, then again at 75, 80, 90 and 95%, and they leave you 24 hours to free up space once the quota has been exceeded.

If the subscription expires, the instance stops, but its projects, its files and its database are kept for 60 days. Three emails warn you before anything is deleted, and renewing within that period gives you back the instance exactly as it was. Subscriptions are monthly, with no commitment: the subscription stays active until the end of the period you have paid for.

Instance backups are offered as an option. The modules you add are part of the configuration of the instance and are backed up and restored along with it. The guide Your data and its security at LizPack brings together everything that protects the content of an instance.

What you do not see, and why

With the hosted offer, you never open a session on the server. Everything is done from the customer area, the online file manager and the QGIS plugin. This is a deliberate choice: without administrator access to the shared servers, LizPack can guarantee their security and their updates. If you need full control of the server, the LizPack Entreprise edition installs the same instances on your own infrastructure; the guide Hosted or on your own servers helps you choose between the two.

None of this locks you in. The published project is a standard QGIS project, the database is a standard PostgreSQL database, and the services are standard OGC services. You can take everything back and run it somewhere else, as explained in the guide Hosting Lizmap or installing it yourself. To go further, see how the instance fits into the full set of LizPack solutions.

Frequently asked questions