Deploying QGIS Server in Ubuntu 20.04

This tutorial guides users on how to install QGIS Server in Ubuntu Linux and provides a well illustrated step-by-step guide on the subject. QGIS Server is an open source GIS server that is used to publish geospatial data and maps across the web leveraging on Open Geospatial Consortium (OGC)’s services. Let us see how the software can be deployed in Ubuntu 20.04. This tutorial assumes that users have already installed Ubuntu 20.04 operating system in their computers.

Installing Pre-requisites

The installation procedure for installing QGIS Server in Ubuntu is somewhat similar to installing QGIS Desktop with just a slight difference between the install commands. There a re some libraries that are required prior to installing the software.

ubuntu login

After starting one’s computer that already has Ubuntu 20.o4 installed, the login screen shown above appears showing the user and a password field. Click on the password field and enter the preset password for the user and click enter key to login. Note that the password to be entered is the one set for the given user during installation.

ubuntu desktop user interface

On logging in successfully, the screen shown above appears showing the Ubuntu Desktop interface with the fossa-like image at the center of it. Click on the command key (similar to windows start key) on your keyboard and type ‘terminal’ as shown below.

ubuntu menu search

An icon with the name ‘terminal’ for the Ubuntu Terminal menu shortcut appears as shown above. This is the Ubuntu Terminal that we will be using to execute some commands.

update and upgrade

Run the command by typing the text shown below and click Enter key:

sudo apt update && sudo apt upgrade -y

which updates and upgrades consecutively outdated packages if any.  Otherwise it will run and show that zero packages were updated and/or upgraded.

update complete

Once the update and upgrading of packages is completed, the terminal window appears as shown above. To clear the terminal screen just type the command shown below and click Enter key.


install qgis requirements

Prior to installing QGIS software, there are two packages that are required:

  1. gnupg – According to Debian Package Repository documentation, this package is used for secure data storage and communication and can be used to encrypt data and create digital signatures. QGIS installation alongside many other installations usually require digital signature verification, a method used to ensure authenticity of the software being installed.
  2. software-properties-common – According to the similar source as above, this package helps in allowing the user to easily manage their distribution and independent vendor software sources. At times it may be already installed in one’s operating system.

Type is the command shown below and click Enter key.

sudo apt install gnupg software-properties-common

The next procedure entails leveraging on the wget package to download and install the QGIS signing key. This will allow us to trust the QGIS installation. Copy and paste the following command in your terminal and click Enter key.

wget -qO - | sudo gpg --no-default-keyring --keyring gnupg-ring:/etc/apt/trusted.gpg.d/qgis-archive.gpg --import

download gnupg keyAfter  running the command, the progress appears in the terminal as shown below.  Note the second and third last lines indicating that a total of 1 key has been processed and installed and this is the signing key.

The next procedure entails allowing read only permission to the QGIS signing key which leverages on the chmod command. The ‘a’ stands for User who is the owner of the file, the “+” sign grants the permissions (meaning grant permission), the ‘r’ stands for the read permission. Therefore in summary the following command assigns read permissions to all the users and groups to QGIS signing key.  For details on this refer here. Copy and paste the following command in the terminal and click Enter.

sudo chmod a+r /etc/apt/trusted.gpg.d/qgis-archive.gpg

In the next procedure we will be installing QGIS Server and the terminal will come in handy.

Installing QGIS Server

As a standard procedure while installing software in Ubuntu, the first step is to add the repository for the software to be installed in the system which is done by the add-apt-repository command. According to the Ubuntu Manpage website, this command adds the repository to the repository lists file. Another item to note in the command below is the text “[arch=amd64]” which tells the system that the installation being made is a 64-bit installation otherwise if your computer has a 32-bit architecture then no need to have it. Therefore, for 32-bit machines the command appears as shown below. Enter the command and click Enter.

Note: for 32-bit only

sudo add-apt-repository "deb $(lsb_release -c -s) main"

and for 64-bit

sudo add-apt-repository "deb [arch=amd=64] $(lsb_release -c -s) main"

Update the packages to ensure that libraries and dependencies necessary for QGIS Server installations are up-to-date.

sudo apt update

After updating the packages and libraries, the next step entails installing QGIS Server, QGIS Desktop and GRASS plugin as well. Note that you can just install QGIS Server only and not bound to install in this way however if you intend to use both desktop and server then you can stick to the command shown below.

sudo apt install qgis qgis-plugin-grass qgis-server -y

After successful installation, the terminal will be back to idle as shown below. Note that the installation process might take sometime depending on the computer processing speed.

For development of server plugins using Python, you can install the python-qgis package. This procedure is not mandatory to run QGIS Server and can be skipped otherwise copy and paste this command in the terminal and click Enter.

sudo apt install python-qgis

To test QGIS Server installation execute the following command in terminal and the resulting message will appear as shown in the image below.


QGIS Server requires a web application server to run and in this tutorial we will be using Apache Server. Another item required is the apache module called mod_fcgid whose work is to implement the FastCGI protocol that is used by QGIS Server and has advantage over the usual CGI protocol in that it can handle concurrent server requests and is also significantly faster then the latter. For more on FastCGI, refer to its documentation.

sudo apt install apache2 libapache2-mod-fcgid

We will create a site configuration file for QGIS Server. For every site one creates, it is mandatory to have a site configuration which is handled or processed by the Apache Web App server. To create a new configuration, we will use nano editor that comes with Ubuntu and through the command shown below. Paste the command in terminal and click Enter.

sudo nano /etc/apache2/sites-available/qgis_server.conf

The above command begins and edit session using nano editor. Note the GNU Nano 4.8 in the header line below. While in the edit session copy and paste the text below. Note that for each path shown as “/home/ubuntu/” needs to be corrected to your home directory path. For exmple, if your user is joseph then your home folder path is “/home/joseph/” therefore correct accordingly.

ServerAdmin webmaster@localhost
ServerName localhost
DocumentRoot /var/www/html

# Apache logs (different than QGIS Server log)
ErrorLog ${APACHE_LOG_DIR}/qgis.demo.error.log
CustomLog ${APACHE_LOG_DIR}/qgis.demo.access.log combined# Longer timeout for WPS... default = 40
FcgidIOTimeout 120

FcgidInitialEnv LC_ALL "en_US.UTF-8"
FcgidInitialEnv LANG "en_US.UTF-8"# QGIS log (different from apache logs)
FcgidInitialEnv QGIS_SERVER_LOG_FILE /var/log/qgis/qgisserver.log

FcgidInitialEnv QGIS_DEBUG 1

# default QGIS project
SetEnv QGIS_PROJECT_FILE /home/ubuntu/projects/world.qgs# QGIS_AUTH_DB_DIR_PATH must lead to a directory writeable by the Server's FCGI process user
FcgidInitialEnv QGIS_AUTH_DB_DIR_PATH "/home/ubuntu/qgisserverdb/"
FcgidInitialEnv QGIS_AUTH_PASSWORD_FILE "/home/ubuntu/qgisserverdb/qgis-auth.db"# Set pg access via pg_service file
SetEnv PGSERVICEFILE /home/ubuntu/.pg_service.conf
FcgidInitialEnv PGPASSFILE "/home/ubuntu/.pgpass"

# Tell QGIS Server instances to use a specific display number
FcgidInitialEnv DISPLAY ":99"

# if qgis-server is installed from packages in debian based distros this is usually /usr/lib/cgi-bin/
# run "locate qgis_mapserv.fcgi" if you don't know where qgis_mapserv.fcgi is
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
<Directory "/usr/lib/cgi-bin/">
AllowOverride None
Options +ExecCGI -MultiViews -SymLinksIfOwnerMatch
Order allow,deny
Allow from all
Require all granted

FcgidMaxRequestLen 26214400
FcgidConnectTimeout 60


After pasting the long configuration text, click Control and x keys at the same time i.e Ctrl + x keys on your keyboard which will show a prompt as shown below.

Click y key to accept changes made (Yes) and nano will exit back to terminal. The next step will be to make a directory for storing QGIS Server logs which are important in monitoring problems that might happen while it is running and also changing ownership of the created folder to apache that is indicated by www-data. Paste the command below in your terminal and click Enter key.

sudo mkdir -p /var/log/qgis && sudo chown www-data:www-data /var/log/qgis

We shall repeat the steps above but now creating a folder for the authentication database and changing ownership to apache (www-data).

sudo mkdir -p /home/ubuntu/qgisserverdb && sudo chown www-data:www-data /home/ubuntu/qgisserverdb

We shall now enable the FastCGI apache module using the a2enmod command that is used to enable apache modules and also enable the site configuration for QGIS Server that we had created in previous steps using the a2ensite command. The second command will prompt us to reload apache server.

sudo a2enmod fcgid && sudo a2ensite qgis_server.conf

let us reload the apache server to pick up the new configuration.

sudo systemctl reload apache2

QGIS Server requires xvfb library that is necessary to act as an X Server and uses the X11 display server protocol to run on machines that have no display hardware or physical input devices such as Ubuntu Server in a cloud infrastructure. Details on the library can be found in Debian’s xvfb documentation.

The next procedure is creating a service file for the xvfb library since it should run as a service. 

sudo nano /etc/systemd/system/xvfb.service

Paste the following lines in the file.

Description=X Virtual Frame Buffer Service

ExecStart=/usr/bin/Xvfb :99 -screen 0 1024x768x24 -ac +extension GLX +render -noreset


Just like in the previous steps, ensure that you click Ctrl + x keys and then click y key and it shall resume the terminal.

We have already created a service but also need to run the service. To run the xvfb service run the following command in terminal.

sudo service xvfb start

We may need to check and ensure that the service is running without issues. To perform that task, we will run the following command in terminal. The green dot indicates that the service is running okay otherwise a white dot shows that the service is not running and in this case we might need to run or re-run the previous command.

sudo service xvfb status

So far we have enabled the QGIS Server site configuration and ensured that the necessary services are running. However, when installing apache for the first time it creates a default site configuration named 000-default.conf  and since we have created the custom configuration for QGIS Server website therefore we may need to disable the default configuration and remain only with QGIS Server site configuration. To do so, run the command below.

sudo a2dissite 000-default.conf && sudo service apache2 reload

Open the browser, in this tutorial we are making use of Firefox browser. open the following link.


The link above opens an XML styled page indicating a error. The error is indicated by tags enclosing the error message as shown below.

Mostly for advanced terminal and apache server users, the logs can be employed to help the server administrator identify the exact error. We are not going to go into much detail on this however, the message shown in the screenshot below indicates that the file with a .qgs extension does not exist.

Download the dataset for this exercise from the QGIS GitHub repository.

A download message window will appear as shown below. Ensure the ‘Save File’ radio button is the selected one and click OK button.

Open the Downloads folder in your computer and the zipped donwload file will appear as shown below.

Open it and identify a folder named qgis-server-tutorial-data and enter into it and copy the items inside it to /home/$USER/projects folder.

Below is the projects folder mentioned in the previous step with all the elements copied into it. Note the world.qgs and world3.qgs which are QGIS project files.

On refreshing or re-opening the first link we had opened in the browser, the following XML page should appear as shown below. The file indicates server capabilities that are well defined in the OGC Web Services.

To view a map, navigate to the following link on your browser and an image map appears as shown below.


Most of the items that make up the link are well defined in the OGC Standards such as the GetMap capabilities, Map location and format of the output which is a JPEG image. We have been able to deploy QGIS Server in Ubuntu 20.04 LTS and rendered a map from it on a browser. Comment or ask a question for clarity purpose.

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.