From 345163d0f8abdd83947bf884513f514f2d13097a Mon Sep 17 00:00:00 2001 From: Denis Rouzaud Date: Tue, 23 Apr 2024 09:34:56 +0200 Subject: [PATCH 1/5] reorganise images per folder + add warning in README --- .github/workflows/build_docker_images.yml | 4 +- README.md | 191 +----------------- desktop.Dockerfile => desktop/Dockerfile | 0 desktop/README.md | 8 + scripts/build-push-docker.sh | 2 +- server.Dockerfile => server/Dockerfile | 2 +- server/README.md | 188 +++++++++++++++++ {conf => server/conf}/nginx-fcgi-sample.conf | 0 {conf => server/conf}/pg_service.conf | 0 {conf => server/conf}/qgis-server-nginx.conf | 0 .../test}/data/test_project/layers/layer.gpkg | Bin .../test}/data/test_project/test_project.qgd | 0 .../test}/data/test_project/test_project.qgs | 0 13 files changed, 203 insertions(+), 192 deletions(-) rename desktop.Dockerfile => desktop/Dockerfile (100%) create mode 100644 desktop/README.md rename server.Dockerfile => server/Dockerfile (97%) create mode 100644 server/README.md rename {conf => server/conf}/nginx-fcgi-sample.conf (100%) rename {conf => server/conf}/pg_service.conf (100%) rename {conf => server/conf}/qgis-server-nginx.conf (100%) rename {test => server/test}/data/test_project/layers/layer.gpkg (100%) rename {test => server/test}/data/test_project/test_project.qgd (100%) rename {test => server/test}/data/test_project/test_project.qgs (100%) diff --git a/.github/workflows/build_docker_images.yml b/.github/workflows/build_docker_images.yml index 5b24d4f..265c11d 100644 --- a/.github/workflows/build_docker_images.yml +++ b/.github/workflows/build_docker_images.yml @@ -44,12 +44,12 @@ jobs: - id: nightly name: building nightly - run: docker build -t qgis/${{ env.DOCKER_TAG }}:nightly -f ${{ matrix.qgis_type }}.Dockerfile --build-arg repo=ubuntu-nightly . + run: docker build -t qgis/${{ env.DOCKER_TAG }}:nightly -f ${{ matrix.qgis_type }}/Dockerfile --build-arg repo=ubuntu-nightly . - name: test if: ${{ matrix.qgis_type == 'server' }} run: | - docker run -d -v $(pwd)/test/data:/io/data -p 8010:80 --name qgis-server qgis/qgis-server:nightly + docker run -d -v $(pwd)/${{ matrix.qgis_type }}/test/data:/io/data -p 8010:80 --name qgis-server qgis/qgis-server:nightly docker exec -i qgis-server dpkg -l qgis-server sleep 5 curl -s 'http://localhost:8010/ogc/test_project?service=WMS&request=GetCapabilities' | grep -ivq exception diff --git a/README.md b/README.md index 8473b5a..93c36fc 100644 --- a/README.md +++ b/README.md @@ -1,191 +1,6 @@ -# QGIS Docker - This repository automates the build of QGIS desktop and QGIS server Docker images. -## QGIS server - -### General information - -The Docker image is built using *Ubuntu 20.04 (focal) and 22.04 (jammy)* and official QGIS DEBs from . -It includes *Nginx* and *Xvfb* and can be used as a standalone service (via HTTP TCP port 80) or as *FCGI* backend (via TCP port 9993). - -### Requisites - -You need **Docker >= 18.04** with `seccomp`. Support for the `statx` syscall, required by Qt 5.10+, may be made necessary in the future. This is generally included in **libseccomp >= 2.3.3**; -a kernel with `statx` support is also required; any kernel newer than 4.11 should be ok. Please check with your vendor. - -Known good configurations are: -- Ubuntu 18.04.2+ -- CentOS 8 -- Fedora 29+ - -See for further details. - -Containers are not tested on hosts running OSes other than Linux. - -### Services provided - -This Docker container exposes HTTP on port `80` via Nginx and a direct FastCGI on port `9993` that can be used directly by an external HTTP proxy (like the provided `docker-compose.yml` does). -A sample Nginx configuration for using it as a *FastCGI* backend is also [provided](conf/nginx-fcgi-sample.conf). - -### Available tags - -Image name: `qgis/qgis-server` - -- **QGIS stable**: `stable` | `stable-ubuntu` -- **QGIS LTR**: `ltr` | `ltr-ubuntu` - -Example: - -```sh -docker pull qgis/qgis-server:ltr -``` - -### Build the container - -#### QGIS stable - -```sh -# stable version -docker build -t qgis/qgis-server:stable . - -# ltr version -docker build --build-arg repo=ubuntu-ltr -t qgis/qgis-server:ltr . -``` - -You may skip this step. The container will be downloaded from the Docker Hub. - -### Run the docker and map host data - -```sh -docker run -v $(pwd)/data:/io/data --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr -``` - -`WMS` and `WFS` for a specific project will be published at `http://localhost:8010/ogc/`. -An `/ows/` endpoint is also available for direct access to the `fcgi` (bypassing the `map=` rewrite). -Direct access to `WFS3` is accessible via `http://localhost:8010/wfs3/`. - - -#### PostgreSQL connection service file (optional) - -The [connection service file](https://www.postgresql.org/docs/12/libpq-pgservice.html) allows connection parameters to be associated with a single service name and thus to be able to use the same QGIS projects in different environments. This could also be achieved with [QGIS authentications](https://docs.qgis.org/3.16/en/docs/user_manual/auth_system/auth_workflows.html#database-authentication). -To use a pg_service file you need to bind mount it as shown in the [docker-compose](docker-compose.yml) or on run: - -```sh --v $(pwd)/conf/pg_service.conf:/etc/postgresql-common/pg_service.conf:ro -``` - - -#### Plugins, fonts and SVG symbols (optional) - -Plugins, custom fonts and SVG can be optionally exposed from host to the containers: - -- plugins: `-v $(pwd)/plugins:/io/plugins` -- fonts: `-v $(pwd)/fonts:/usr/share/fonts` -- svg symbols: `-v $(pwd)/svg:/var/lib/qgis/.local/share/QGIS/QGIS3/profiles/default/svg` - -Example: - -```sh -docker run -v $(pwd)/data:/io/data -v $(pwd)/plugins:/io/plugins -v $(pwd)/fonts:/usr/share/fonts --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr -``` - -#### Access the container via bash - -```sh -docker exec -ti qgis-server /bin/bash -``` - -where `qgis-server` is the name of the container. - -#### Logs and debugging - -QGIS server log can retreived via `docker logs` - -```sh -docker logs [-f] qgis-server -``` - -where `qgis-server` is the name of the container. - -Default log level is set to `warning`. Log level can be increased during container deployment passing the `-e QGIS_SERVER_LOG_LEVEL=0` option: - -```sh -docker run -e QGIS_SERVER_LOG_LEVEL=0 -v $(pwd)/data:/io/data -v $(pwd)/plugins:/io/plugins --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr -``` - -### Run multiple instances of QGIS server - -Adjust first the configuration in `conf/nginx.conf` with the proper number of expected workers -and `docker-compose.yml` with the path of data folder on the host. - -Then: - -```sh -docker-compose up -d --scale qgis-server=N -``` - -Where N is the number of expected QGIS server workers. - - -### Data dir structure - -`$(pwd)/data` must have the following structure: - -```text -data - | - |-- - |-- .qgs -``` - -[oq-consolidate](https://github.com/gem/oq-consolidate) may helps you in exporting data suitable for QGIS server (consolidating project and layers). - -`$(pwd)/plugins` must have the following structure: - -```text -plugins - | - |-- - |-- .py - |-- metadata.txt - |-- __init__.py -``` - -Custom fonts are loaded into `/usr/share/fonts`. `fc-cache` is run when container is started. - -### Runtime customizations - -The following variables can be customized during container deployment: - -#### Nginx - -When `SKIP_NGINX` is set to a different value than `0` or `false` the embedded copy of Nginx will not be started and an external reverse proxy is then required to access the FastCGI QGIS backend. - -- `SKIP_NGINX`: default is *unset* (do not skip Nginx startup) - -#### QGIS - -- `QGIS_SERVER_LOG_LEVEL`: default is `1` -- `QGIS_SERVER_PARALLEL_RENDERING`: default is `true` -- `QGIS_SERVER_MAX_THREADS`: default is `2` -- `QGIS_SERVER_WMS_MAX_WIDTH`: not set by default -- `QGIS_SERVER_WMS_MAX_WIDTH`: not set by default - -See [QGIS server documentation](https://docs.qgis.org/testing/en/docs/server_manual/config.html#environment-variables) for further details. - -It is also possible to customized the ID of the user running QGIS server processes when it is required to write to host volumes (see [notes](#notes)): - -- `QGIS_USER`: default is `nginx`, a numerical id must be proivided - -Example: `docker run -e QGIS_USER=1000` or `docker run -e QGIS_USER=$(id -u qgis)` - -### Notes - -GeoPackages do not play well with multiple processes having gpkg files opened in `rw` mode. By default QGIS server processes lack write permission on `/io/data`. -If it is required to let QGIS server write data to `/io/data` make sure that either you are using a process-safe datastore (i.e. a Postgres backend) or you are -limiting horizontal scaling to one container only. QGIS server user can be customized via the `QGIS_USER` environment variable. - -## QGIS Desktop +### Warning -There is currently no documentation how to run the QGIS Desktop via docker. +There are discussions on how to build these images and they are not considered stable. +They are considered as NOT production ready. diff --git a/desktop.Dockerfile b/desktop/Dockerfile similarity index 100% rename from desktop.Dockerfile rename to desktop/Dockerfile diff --git a/desktop/README.md b/desktop/README.md new file mode 100644 index 0000000..7a10554 --- /dev/null +++ b/desktop/README.md @@ -0,0 +1,8 @@ +## QGIS Desktop standalone + +A simple QGIS desktop Docker image + +### Warning + +There are discussions on how to build these images and they are not considered stable. +They are considered as NOT production ready. \ No newline at end of file diff --git a/scripts/build-push-docker.sh b/scripts/build-push-docker.sh index 478390a..5709eac 100755 --- a/scripts/build-push-docker.sh +++ b/scripts/build-push-docker.sh @@ -43,5 +43,5 @@ for TAG in ${TAGS}; do ALL_TAGS="${ALL_TAGS} --tag qgis/${REPO}:${TAG}" done -docker buildx build --push --platform linux/amd64,linux/arm64 --build-arg ubuntu_dist=${UBUNTU_DIST} --build-arg repo=${QGIS_UBUNTU_PPA} ${ALL_TAGS} -f ${QGIS_TYPE}.Dockerfile . +docker buildx build --push --platform linux/amd64,linux/arm64 --build-arg ubuntu_dist=${UBUNTU_DIST} --build-arg repo=${QGIS_UBUNTU_PPA} ${ALL_TAGS} -f ${QGIS_TYPE}/Dockerfile . diff --git a/server.Dockerfile b/server/Dockerfile similarity index 97% rename from server.Dockerfile rename to server/Dockerfile index 447236d..d4159a5 100644 --- a/server.Dockerfile +++ b/server/Dockerfile @@ -37,7 +37,7 @@ RUN apt update && apt install -y gnupg wget software-properties-common && \ # This part is kept to allow the container to be used in # standalone mode, without composing it with 'nginx' ADD conf/qgis-server-nginx.conf /etc/nginx/nginx.conf -ADD start-xvfb-nginx.sh /usr/local/bin/start-xvfb-nginx.sh +ADD ../start-xvfb-nginx.sh /usr/local/bin/start-xvfb-nginx.sh ENV QGIS_PREFIX_PATH /usr ENV QGIS_PLUGINPATH /io/plugins diff --git a/server/README.md b/server/README.md new file mode 100644 index 0000000..81037ba --- /dev/null +++ b/server/README.md @@ -0,0 +1,188 @@ +## QGIS server + +### Warning + +There are discussions on how to build these images and they are not considered stable. +They are considered as NOT production ready. + +### General information + +The Docker image is built using *Ubuntu 20.04 (focal) and 22.04 (jammy)* and official QGIS DEBs from . +It includes *Nginx* and *Xvfb* and can be used as a standalone service (via HTTP TCP port 80) or as *FCGI* backend (via TCP port 9993). + +### Requisites + +You need **Docker >= 18.04** with `seccomp`. Support for the `statx` syscall, required by Qt 5.10+, may be made necessary in the future. This is generally included in **libseccomp >= 2.3.3**; +a kernel with `statx` support is also required; any kernel newer than 4.11 should be ok. Please check with your vendor. + +Known good configurations are: +- Ubuntu 18.04.2+ +- CentOS 8 +- Fedora 29+ + +See for further details. + +Containers are not tested on hosts running OSes other than Linux. + +### Services provided + +This Docker container exposes HTTP on port `80` via Nginx and a direct FastCGI on port `9993` that can be used directly by an external HTTP proxy (like the provided `docker-compose.yml` does). +A sample Nginx configuration for using it as a *FastCGI* backend is also [provided](conf/nginx-fcgi-sample.conf). + +### Available tags + +Image name: `qgis/qgis-server` + +- **QGIS stable**: `stable` | `stable-ubuntu` +- **QGIS LTR**: `ltr` | `ltr-ubuntu` + +Example: + +```sh +docker pull qgis/qgis-server:ltr +``` + +### Build the container + +#### QGIS stable + +```sh +# stable version +docker build -t qgis/qgis-server:stable . + +# ltr version +docker build --build-arg repo=ubuntu-ltr -t qgis/qgis-server:ltr . +``` + +You may skip this step. The container will be downloaded from the Docker Hub. + +### Run the docker and map host data + +```sh +docker run -v $(pwd)/data:/io/data --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr +``` + +`WMS` and `WFS` for a specific project will be published at `http://localhost:8010/ogc/`. +An `/ows/` endpoint is also available for direct access to the `fcgi` (bypassing the `map=` rewrite). +Direct access to `WFS3` is accessible via `http://localhost:8010/wfs3/`. + + +#### PostgreSQL connection service file (optional) + +The [connection service file](https://www.postgresql.org/docs/12/libpq-pgservice.html) allows connection parameters to be associated with a single service name and thus to be able to use the same QGIS projects in different environments. This could also be achieved with [QGIS authentications](https://docs.qgis.org/3.16/en/docs/user_manual/auth_system/auth_workflows.html#database-authentication). +To use a pg_service file you need to bind mount it as shown in the [docker-compose](docker-compose.yml) or on run: + +```sh +-v $(pwd)/conf/pg_service.conf:/etc/postgresql-common/pg_service.conf:ro +``` + + +#### Plugins, fonts and SVG symbols (optional) + +Plugins, custom fonts and SVG can be optionally exposed from host to the containers: + +- plugins: `-v $(pwd)/plugins:/io/plugins` +- fonts: `-v $(pwd)/fonts:/usr/share/fonts` +- svg symbols: `-v $(pwd)/svg:/var/lib/qgis/.local/share/QGIS/QGIS3/profiles/default/svg` + +Example: + +```sh +docker run -v $(pwd)/data:/io/data -v $(pwd)/plugins:/io/plugins -v $(pwd)/fonts:/usr/share/fonts --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr +``` + +#### Access the container via bash + +```sh +docker exec -ti qgis-server /bin/bash +``` + +where `qgis-server` is the name of the container. + +#### Logs and debugging + +QGIS server log can retreived via `docker logs` + +```sh +docker logs [-f] qgis-server +``` + +where `qgis-server` is the name of the container. + +Default log level is set to `warning`. Log level can be increased during container deployment passing the `-e QGIS_SERVER_LOG_LEVEL=0` option: + +```sh +docker run -e QGIS_SERVER_LOG_LEVEL=0 -v $(pwd)/data:/io/data -v $(pwd)/plugins:/io/plugins --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr +``` + +### Run multiple instances of QGIS server + +Adjust first the configuration in `conf/nginx.conf` with the proper number of expected workers +and `docker-compose.yml` with the path of data folder on the host. + +Then: + +```sh +docker-compose up -d --scale qgis-server=N +``` + +Where N is the number of expected QGIS server workers. + + +### Data dir structure + +`$(pwd)/data` must have the following structure: + +```text +data + | + |-- + |-- .qgs +``` + +[oq-consolidate](https://github.com/gem/oq-consolidate) may helps you in exporting data suitable for QGIS server (consolidating project and layers). + +`$(pwd)/plugins` must have the following structure: + +```text +plugins + | + |-- + |-- .py + |-- metadata.txt + |-- __init__.py +``` + +Custom fonts are loaded into `/usr/share/fonts`. `fc-cache` is run when container is started. + +### Runtime customizations + +The following variables can be customized during container deployment: + +#### Nginx + +When `SKIP_NGINX` is set to a different value than `0` or `false` the embedded copy of Nginx will not be started and an external reverse proxy is then required to access the FastCGI QGIS backend. + +- `SKIP_NGINX`: default is *unset* (do not skip Nginx startup) + +#### QGIS + +- `QGIS_SERVER_LOG_LEVEL`: default is `1` +- `QGIS_SERVER_PARALLEL_RENDERING`: default is `true` +- `QGIS_SERVER_MAX_THREADS`: default is `2` +- `QGIS_SERVER_WMS_MAX_WIDTH`: not set by default +- `QGIS_SERVER_WMS_MAX_WIDTH`: not set by default + +See [QGIS server documentation](https://docs.qgis.org/testing/en/docs/server_manual/config.html#environment-variables) for further details. + +It is also possible to customized the ID of the user running QGIS server processes when it is required to write to host volumes (see [notes](#notes)): + +- `QGIS_USER`: default is `nginx`, a numerical id must be proivided + +Example: `docker run -e QGIS_USER=1000` or `docker run -e QGIS_USER=$(id -u qgis)` + +### Notes + +GeoPackages do not play well with multiple processes having gpkg files opened in `rw` mode. By default QGIS server processes lack write permission on `/io/data`. +If it is required to let QGIS server write data to `/io/data` make sure that either you are using a process-safe datastore (i.e. a Postgres backend) or you are +limiting horizontal scaling to one container only. QGIS server user can be customized via the `QGIS_USER` environment variable. diff --git a/conf/nginx-fcgi-sample.conf b/server/conf/nginx-fcgi-sample.conf similarity index 100% rename from conf/nginx-fcgi-sample.conf rename to server/conf/nginx-fcgi-sample.conf diff --git a/conf/pg_service.conf b/server/conf/pg_service.conf similarity index 100% rename from conf/pg_service.conf rename to server/conf/pg_service.conf diff --git a/conf/qgis-server-nginx.conf b/server/conf/qgis-server-nginx.conf similarity index 100% rename from conf/qgis-server-nginx.conf rename to server/conf/qgis-server-nginx.conf diff --git a/test/data/test_project/layers/layer.gpkg b/server/test/data/test_project/layers/layer.gpkg similarity index 100% rename from test/data/test_project/layers/layer.gpkg rename to server/test/data/test_project/layers/layer.gpkg diff --git a/test/data/test_project/test_project.qgd b/server/test/data/test_project/test_project.qgd similarity index 100% rename from test/data/test_project/test_project.qgd rename to server/test/data/test_project/test_project.qgd diff --git a/test/data/test_project/test_project.qgs b/server/test/data/test_project/test_project.qgs similarity index 100% rename from test/data/test_project/test_project.qgs rename to server/test/data/test_project/test_project.qgs From 3b509d598e70d7374c1984b81544c90d46958a88 Mon Sep 17 00:00:00 2001 From: Denis Rouzaud Date: Tue, 23 Apr 2024 09:51:31 +0200 Subject: [PATCH 2/5] fix context --- .github/workflows/build_docker_images.yml | 2 +- .gitignore | 1 + scripts/build-push-docker.sh | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build_docker_images.yml b/.github/workflows/build_docker_images.yml index 265c11d..2340b0e 100644 --- a/.github/workflows/build_docker_images.yml +++ b/.github/workflows/build_docker_images.yml @@ -44,7 +44,7 @@ jobs: - id: nightly name: building nightly - run: docker build -t qgis/${{ env.DOCKER_TAG }}:nightly -f ${{ matrix.qgis_type }}/Dockerfile --build-arg repo=ubuntu-nightly . + run: docker build -t qgis/${{ env.DOCKER_TAG }}:nightly --build-arg repo=ubuntu-nightly ${{ matrix.qgis_type }} - name: test if: ${{ matrix.qgis_type == 'server' }} diff --git a/.gitignore b/.gitignore index a47fb1d..91e2d02 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ +*.orig .idea __pycache__ \ No newline at end of file diff --git a/scripts/build-push-docker.sh b/scripts/build-push-docker.sh index 5709eac..4a80c82 100755 --- a/scripts/build-push-docker.sh +++ b/scripts/build-push-docker.sh @@ -43,5 +43,5 @@ for TAG in ${TAGS}; do ALL_TAGS="${ALL_TAGS} --tag qgis/${REPO}:${TAG}" done -docker buildx build --push --platform linux/amd64,linux/arm64 --build-arg ubuntu_dist=${UBUNTU_DIST} --build-arg repo=${QGIS_UBUNTU_PPA} ${ALL_TAGS} -f ${QGIS_TYPE}/Dockerfile . +docker buildx build --push --platform linux/amd64,linux/arm64 --build-arg ubuntu_dist=${UBUNTU_DIST} --build-arg repo=${QGIS_UBUNTU_PPA} ${ALL_TAGS} ${QGIS_TYPE} From 1b27042957576a0130719d99c0cfc2d6b51243fa Mon Sep 17 00:00:00 2001 From: Denis Rouzaud Date: Tue, 23 Apr 2024 09:59:47 +0200 Subject: [PATCH 3/5] fix path --- server/Dockerfile | 2 +- start-xvfb-nginx.sh => server/start-xvfb-nginx.sh | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename start-xvfb-nginx.sh => server/start-xvfb-nginx.sh (100%) diff --git a/server/Dockerfile b/server/Dockerfile index d4159a5..447236d 100644 --- a/server/Dockerfile +++ b/server/Dockerfile @@ -37,7 +37,7 @@ RUN apt update && apt install -y gnupg wget software-properties-common && \ # This part is kept to allow the container to be used in # standalone mode, without composing it with 'nginx' ADD conf/qgis-server-nginx.conf /etc/nginx/nginx.conf -ADD ../start-xvfb-nginx.sh /usr/local/bin/start-xvfb-nginx.sh +ADD start-xvfb-nginx.sh /usr/local/bin/start-xvfb-nginx.sh ENV QGIS_PREFIX_PATH /usr ENV QGIS_PLUGINPATH /io/plugins diff --git a/start-xvfb-nginx.sh b/server/start-xvfb-nginx.sh similarity index 100% rename from start-xvfb-nginx.sh rename to server/start-xvfb-nginx.sh From f424f419c22336e6ee18bc58bcfe19fbddd45b07 Mon Sep 17 00:00:00 2001 From: Denis Rouzaud Date: Tue, 23 Apr 2024 10:37:06 +0200 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Jakob Miksch --- README.md | 9 ++- desktop/README.md | 4 +- server/README.md | 158 ++-------------------------------------------- 3 files changed, 16 insertions(+), 155 deletions(-) diff --git a/README.md b/README.md index 93c36fc..2795a4a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,13 @@ This repository automates the build of QGIS desktop and QGIS server Docker images. -### Warning +# QGIS Docker Images + +This repository automates the build of QGIS desktop and QGIS server Docker images. The respective docs are located here: + +- [QGIS Server](./server/README.md) +- [QGIS Desktop](./desktop/README.md) + +**Warning**: There are discussions on how to build these images and they are not considered stable. They are considered as NOT production ready. diff --git a/desktop/README.md b/desktop/README.md index 7a10554..9aec490 100644 --- a/desktop/README.md +++ b/desktop/README.md @@ -1,8 +1,8 @@ -## QGIS Desktop standalone +# QGIS Desktop standalone A simple QGIS desktop Docker image -### Warning +**Warning** There are discussions on how to build these images and they are not considered stable. They are considered as NOT production ready. \ No newline at end of file diff --git a/server/README.md b/server/README.md index 81037ba..ecef8a9 100644 --- a/server/README.md +++ b/server/README.md @@ -1,16 +1,16 @@ -## QGIS server +# QGIS Server -### Warning +**Warning** There are discussions on how to build these images and they are not considered stable. They are considered as NOT production ready. -### General information +## General information The Docker image is built using *Ubuntu 20.04 (focal) and 22.04 (jammy)* and official QGIS DEBs from . It includes *Nginx* and *Xvfb* and can be used as a standalone service (via HTTP TCP port 80) or as *FCGI* backend (via TCP port 9993). -### Requisites +## Requisites You need **Docker >= 18.04** with `seccomp`. Support for the `statx` syscall, required by Qt 5.10+, may be made necessary in the future. This is generally included in **libseccomp >= 2.3.3**; a kernel with `statx` support is also required; any kernel newer than 4.11 should be ok. Please check with your vendor. @@ -24,12 +24,12 @@ See for further details. Containers are not tested on hosts running OSes other than Linux. -### Services provided +## Services provided This Docker container exposes HTTP on port `80` via Nginx and a direct FastCGI on port `9993` that can be used directly by an external HTTP proxy (like the provided `docker-compose.yml` does). A sample Nginx configuration for using it as a *FastCGI* backend is also [provided](conf/nginx-fcgi-sample.conf). -### Available tags +## Available tags Image name: `qgis/qgis-server` @@ -40,149 +40,3 @@ Example: ```sh docker pull qgis/qgis-server:ltr -``` - -### Build the container - -#### QGIS stable - -```sh -# stable version -docker build -t qgis/qgis-server:stable . - -# ltr version -docker build --build-arg repo=ubuntu-ltr -t qgis/qgis-server:ltr . -``` - -You may skip this step. The container will be downloaded from the Docker Hub. - -### Run the docker and map host data - -```sh -docker run -v $(pwd)/data:/io/data --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr -``` - -`WMS` and `WFS` for a specific project will be published at `http://localhost:8010/ogc/`. -An `/ows/` endpoint is also available for direct access to the `fcgi` (bypassing the `map=` rewrite). -Direct access to `WFS3` is accessible via `http://localhost:8010/wfs3/`. - - -#### PostgreSQL connection service file (optional) - -The [connection service file](https://www.postgresql.org/docs/12/libpq-pgservice.html) allows connection parameters to be associated with a single service name and thus to be able to use the same QGIS projects in different environments. This could also be achieved with [QGIS authentications](https://docs.qgis.org/3.16/en/docs/user_manual/auth_system/auth_workflows.html#database-authentication). -To use a pg_service file you need to bind mount it as shown in the [docker-compose](docker-compose.yml) or on run: - -```sh --v $(pwd)/conf/pg_service.conf:/etc/postgresql-common/pg_service.conf:ro -``` - - -#### Plugins, fonts and SVG symbols (optional) - -Plugins, custom fonts and SVG can be optionally exposed from host to the containers: - -- plugins: `-v $(pwd)/plugins:/io/plugins` -- fonts: `-v $(pwd)/fonts:/usr/share/fonts` -- svg symbols: `-v $(pwd)/svg:/var/lib/qgis/.local/share/QGIS/QGIS3/profiles/default/svg` - -Example: - -```sh -docker run -v $(pwd)/data:/io/data -v $(pwd)/plugins:/io/plugins -v $(pwd)/fonts:/usr/share/fonts --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr -``` - -#### Access the container via bash - -```sh -docker exec -ti qgis-server /bin/bash -``` - -where `qgis-server` is the name of the container. - -#### Logs and debugging - -QGIS server log can retreived via `docker logs` - -```sh -docker logs [-f] qgis-server -``` - -where `qgis-server` is the name of the container. - -Default log level is set to `warning`. Log level can be increased during container deployment passing the `-e QGIS_SERVER_LOG_LEVEL=0` option: - -```sh -docker run -e QGIS_SERVER_LOG_LEVEL=0 -v $(pwd)/data:/io/data -v $(pwd)/plugins:/io/plugins --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr -``` - -### Run multiple instances of QGIS server - -Adjust first the configuration in `conf/nginx.conf` with the proper number of expected workers -and `docker-compose.yml` with the path of data folder on the host. - -Then: - -```sh -docker-compose up -d --scale qgis-server=N -``` - -Where N is the number of expected QGIS server workers. - - -### Data dir structure - -`$(pwd)/data` must have the following structure: - -```text -data - | - |-- - |-- .qgs -``` - -[oq-consolidate](https://github.com/gem/oq-consolidate) may helps you in exporting data suitable for QGIS server (consolidating project and layers). - -`$(pwd)/plugins` must have the following structure: - -```text -plugins - | - |-- - |-- .py - |-- metadata.txt - |-- __init__.py -``` - -Custom fonts are loaded into `/usr/share/fonts`. `fc-cache` is run when container is started. - -### Runtime customizations - -The following variables can be customized during container deployment: - -#### Nginx - -When `SKIP_NGINX` is set to a different value than `0` or `false` the embedded copy of Nginx will not be started and an external reverse proxy is then required to access the FastCGI QGIS backend. - -- `SKIP_NGINX`: default is *unset* (do not skip Nginx startup) - -#### QGIS - -- `QGIS_SERVER_LOG_LEVEL`: default is `1` -- `QGIS_SERVER_PARALLEL_RENDERING`: default is `true` -- `QGIS_SERVER_MAX_THREADS`: default is `2` -- `QGIS_SERVER_WMS_MAX_WIDTH`: not set by default -- `QGIS_SERVER_WMS_MAX_WIDTH`: not set by default - -See [QGIS server documentation](https://docs.qgis.org/testing/en/docs/server_manual/config.html#environment-variables) for further details. - -It is also possible to customized the ID of the user running QGIS server processes when it is required to write to host volumes (see [notes](#notes)): - -- `QGIS_USER`: default is `nginx`, a numerical id must be proivided - -Example: `docker run -e QGIS_USER=1000` or `docker run -e QGIS_USER=$(id -u qgis)` - -### Notes - -GeoPackages do not play well with multiple processes having gpkg files opened in `rw` mode. By default QGIS server processes lack write permission on `/io/data`. -If it is required to let QGIS server write data to `/io/data` make sure that either you are using a process-safe datastore (i.e. a Postgres backend) or you are -limiting horizontal scaling to one container only. QGIS server user can be customized via the `QGIS_USER` environment variable. From d1ae10b7e785545b406377b950bc4c699a44bfe4 Mon Sep 17 00:00:00 2001 From: Denis Rouzaud Date: Tue, 23 Apr 2024 10:38:29 +0200 Subject: [PATCH 5/5] Update README.md Co-authored-by: Jakob Miksch --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 2795a4a..427b3f6 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -This repository automates the build of QGIS desktop and QGIS server Docker images. - # QGIS Docker Images This repository automates the build of QGIS desktop and QGIS server Docker images. The respective docs are located here: