8. Containerized deployment

There are many ways to use containerized application, from the most simple (simple Docker images) to sophisticated (Kubernetes and so on).


This kind of deployment needs the docker application to be installed and running. Check this tutorial.


Docker run pre packaged application (aka images) which can be retrieved as sources (Dockerfile and resources) to build or already built from registries (private or public).


QGIS Debian-Ubuntu package downloads need a valid gpg authentication key. Please refer to the installation pages to update the following Dockerfile.

8.1. Simple docker images

As the docker image does not exist in a public registry. you will need to build it. To do so create a directory qgis-server and within its directory:

  • create a file Dockerfile with this content:

FROM debian:bullseye-slim


RUN apt-get update \
    && apt-get install --no-install-recommends --no-install-suggests --allow-unauthenticated -y \
        gnupg \
        ca-certificates \
        wget \
        locales \
    && localedef -i en_US -f UTF-8 en_US.UTF-8 \
    # Add the current key for package downloading
    # Please refer to QGIS install documentation (https://www.qgis.org/fr/site/forusers/alldownloads.html#debian-ubuntu)
    && mkdir -m755 -p /etc/apt/keyrings \
    && wget -O /etc/apt/keyrings/qgis-archive-keyring.gpg https://download.qgis.org/downloads/qgis-archive-keyring.gpg \
    # Add repository for latest version of qgis-server
    # Please refer to QGIS repositories documentation if you want other version (https://qgis.org/en/site/forusers/alldownloads.html#repositories)
    && echo "deb [signed-by=/etc/apt/keyrings/qgis-archive-keyring.gpg] https://qgis.org/debian bullseye main" | tee /etc/apt/sources.list.d/qgis.list \
    && apt-get update \
    && apt-get install --no-install-recommends --no-install-suggests --allow-unauthenticated -y \
        qgis-server \
        spawn-fcgi \
        xauth \
        xvfb \
    && apt-get remove --purge -y \
        gnupg \
        wget \
    && rm -rf /var/lib/apt/lists/*

RUN useradd -m qgis

ADD https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini /tini
RUN chmod +x /tini


COPY cmd.sh /home/qgis/cmd.sh
RUN chmod -R 777 /home/qgis/cmd.sh
RUN chown qgis:qgis /home/qgis/cmd.sh

USER qgis
WORKDIR /home/qgis

ENTRYPOINT ["/tini", "--"]

CMD ["/home/qgis/cmd.sh"]
  • create a file cmd.sh with this content:


[[ $DEBUG == "1" ]] && env

exec /usr/bin/xvfb-run --auto-servernum --server-num=1 /usr/bin/spawn-fcgi -p 5555 -n -d /home/qgis -- /usr/lib/cgi-bin/qgis_mapserv.fcgi
  • build the image with:

docker build -f Dockerfile -t qgis-server ./

8.1.1. First run

To run the server you will need a QGIS project file. You can use one of yours or pick this sample.

To do so, create a directory data within the directory qgis-server and copy your file in it. To comply with the following explanations, rename it to osm.qgs.


You may need to add advertised URLs under the QGIS Server tab of the Project ► Properties if the GetCapabilites are broken. For example if your server is exposed on port 8080, you will put this for advertised URL http://localhost:8080/qgis-server/. More information available in section Configure your project and subsequent.

Now, you can run the server with:

docker network create qgis
docker run -d --rm --name qgis-server --net=qgis --hostname=qgis-server \
              -v $(pwd)/data:/data:ro -p 5555:5555 \
              -e "QGIS_PROJECT_FILE=/data/osm.qgs" \

Options used:

  • -d: run in the background

  • –rm: remove the container when it is stopped

  • –name: name of the container to be created

  • –net: (previously created) sub network

  • –hostname: container hostname, for later referencing

  • -v: local data directory to be mounted in the container

  • -p: host/container port mapping

  • -e: environment variable to be used in the container

To check, type docker ps | grep qgis-server and you should see a line with qgis-server:

CONTAINER ID   IMAGE         COMMAND                  CREATED         STATUS         PORTS                    NAMES
4de8192da76e   qgis-server   "/tini -- /home/qgis…"   3 seconds ago   Up 2 seconds>5555/tcp   qgis-server

8.1.2. Usable sample

As the server is only accepting fastcgi connections, you need an HTTP server that handles this protocol. To do so we have to create a simple Nginx configuration file and start a Nginx image.

Create a file nginx.conf in the current directory with this content:

server {
  listen 80;
  server_name _;
  location / {
    root  /usr/share/nginx/html;
    index index.html index.htm;
  location /qgis-server {
    proxy_buffers 16 16k;
    proxy_buffer_size 16k;
    gzip off;
    include fastcgi_params;
    fastcgi_pass qgis-server:5555;

And type this command:

docker run -d --rm --name nginx --net=qgis --hostname=nginx \
              -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro -p 8080:80 \

To check capabilities availability, type in a browser http://localhost:8080/qgis-server/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities

8.1.3. Cleanup

To cleanup the running images, type:

docker stop qgis-server nginx

8.2. Docker stacks

The previous method is scriptable, but not easily packageable nor standardized or easily manageable.

To work with a docker image set you could use a docker stack managed by an orchestrator. In a stack, the images are working in the same private network, and you can start / stop the whole stack or deploy the stack to other workers. There are many orchestrators, for example Swarm, Kubernetes and Mesos.

In the following, we will present simple configurations for testing purposes. They are not suitable for production.

8.2.1. Swarm/docker-compose

Docker now has its own orchestrator: Swarm (compatible with docker-compose files). You have to enable it (the Mac version will also work with Linux).

Stack description

Now that you have Swarm working, create the service file (see Deploy to Swarm) qgis-stack.yaml:

version: '3.7'

    # Should use version with utf-8 locale support:
    image: qgis-server:latest
    - REPLACE_WITH_FULL_PATH/data:/data:ro
    - LANG=en_EN.UTF-8
    - QGIS_PROJECT_FILE=/data/osm.qgs
    - QGIS_SERVER_LOG_LEVEL=0  # INFO (log all requests)
    - DEBUG=1                  # display env before spawning QGIS Server

    image: nginx:1.13
    - 8080:80
    - REPLACE_WITH_FULL_PATH/nginx.conf:/etc/nginx/conf.d/default.conf:ro
    - qgis-server

To deploy (or update) the stack, type:

docker stack deploy -c qgis-stack.yaml qgis-stack

Check the stack deployment status until you obtain 1/1 in the replicas column:

docker stack services qgis-stack

Something like:

ID                  NAME                MODE                REPLICAS            IMAGE               PORTS
gmx7ewlvwsqt        qgis_nginx          replicated          1/1                 nginx:1.13          *:8080->80/tcp
l0v2e7cl43u3        qgis_qgis-server    replicated          1/1                 qgis-server:latest

To check WMS capabilities, type in a web browser http://localhost:8080/qgis-server/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities


To cleanup, type:

docker stack rm qgis-stack

8.2.2. Kubernetes


If you have a Docker Desktop installation, using Kubernetes (aka k8s) is pretty straight forward: enable k8s.

If not, follow the minikube tutorial or microk8s for Ubuntu.

As Kubernetes installation can be really complex, we will only focus on aspects used by this demo. For further / deeper information, check the official documentation.


microk8s needs extra steps: you have to enable the registry and tag the qgis-server image in order to have Kubernetes to find the created images.

First, enable the registry:

microk8s enable dashboard dns registry

Then, tag and push the image to your newly created registry:

docker tag qgis-server && docker push

Finally, add or complete the /etc/docker/daemon.json to have your registry listed in the insecure-registries field:

  "insecure-registries": [""]

Creating manifests

Kubernetes describes the objects to deploy in yaml manifests. There are many different kinds, but we will only use deployments (handle pods, i.e. docker images) and services to expose the deployments to internal or external purposes.

Deployment manifests

Create a file deployments.yaml with this content:

apiVersion: apps/v1
kind: Deployment
  name: qgis-server
  namespace: default
  replicas: 1
      myLabel: qgis-server
        myLabel: qgis-server
        - name: qgis-server
          image: localhost:32000/qgis-server:latest
          imagePullPolicy: IfNotPresent
            - name: LANG
              value: en_EN.UTF-8
            - name: QGIS_PROJECT_FILE
              value: /data/osm.qgs
            - name: QGIS_SERVER_LOG_LEVEL
              value: "0"
            - name: DEBUG
              value: "1"
            - containerPort: 5555
            - name: qgis-data
              mountPath: /data/
        - name: qgis-data
            path: REPLACE_WITH_FULL_PATH/data

apiVersion: apps/v1
kind: Deployment
  name: qgis-nginx
  namespace: default
  replicas: 1
      myLabel: qgis-nginx
        myLabel: qgis-nginx
        - name: qgis-nginx
          image: nginx:1.13
            - containerPort: 80
            - name: nginx-conf
              mountPath: /etc/nginx/conf.d/default.conf
        - name: nginx-conf
            path: REPLACE_WITH_FULL_PATH/nginx.conf
Service manifests

Create a file services.yaml with this content:

apiVersion: v1
kind: Service
  name: qgis-server
  namespace: default
  type: ClusterIP
    myLabel: qgis-server
    - port: 5555
      targetPort: 5555
apiVersion: v1
kind: Service
  name: qgis-nginx
  namespace: default
  type: NodePort
    myLabel: qgis-nginx
    - port: 80
      targetPort: 80
      nodePort: 30080

Deploying manifests

To deploy the images and services in Kubernetes, one can use the dashboard (click on the + on the upper right) or the command line.


When using the command line with microk8s you will have to prefix each command with microk8s.

To deploy or update your manifests:

kubectl apply -k ./

To check what is currently deployed:

kubectl get pods,services,deployment

You should obtain something like:

NAME                               READY   STATUS    RESTARTS   AGE
pod/qgis-nginx-54845ff6f6-8skp9    1/1     Running   0          27m
pod/qgis-server-75df8ddd89-c7t7s   1/1     Running   0          27m

NAME                       TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)        AGE
service/Kubernetes         ClusterIP     <none>        443/TCP        5h51m
service/qgis-exec-server   ClusterIP   <none>        5555/TCP       35m
service/qgis-nginx         NodePort   <none>        80:30080/TCP   27m
service/qgis-server        ClusterIP   <none>        5555/TCP       27m

NAME                          READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/qgis-nginx    1/1     1            1           27m
deployment.apps/qgis-server   1/1     1            1           27m

To read nginx/qgis logs, type:

kubectl logs -f POD_NAME

To check WMS capabilities, type in a web browser http://localhost:30080/qgis-server/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities


To clean up, type:

kubectl delete -n default service/qgis-server service/qgis-nginx deployment/qgis-nginx deployment/qgis-server

8.3. Cloud deployment

Managing your own cluster of servers to handle the deployment of containerized applications, is a complex job. You have to handle multiple issues, such as hardware, bandwidth and security at different levels.

Cloud deployment solutions can be a good alternative when you do not want to focus on infrastructure management.

A cloud deployment may use proprietary mechanisms, but they are also compatible with the stages explained previously (docker images and stack management).

8.3.1. AWS usecase

With Amazon AWS, through ECS (Elastic Container Service) functionalities, you can use docker-compose or Kubernetes compatible wrappers to manage your stack. You will have to create an image registry for your custom images to be accessible.

To use docker-compose alike functionalities, you need to install the ecs-cli client and have proper permissions / roles. Then, with the help of the ecs-cli compose commands, you can reuse the stack description.

To use Kubernetes, you can use the AWS web console or the command line tool eksctl and have the proper permissions / roles. Then with a well configured kubectl environment, you can reuse the Kubernetes manifests.