From e64d3a2b588e15c819671abba1a2252a13793432 Mon Sep 17 00:00:00 2001 From: Jakob Miksch Date: Mon, 22 Apr 2024 11:40:31 +0200 Subject: [PATCH] Cleanup docs (#99) Co-authored-by: Jakob Miksch --- README.md | 103 +++++++++++++++++++++++------------------------------- 1 file changed, 43 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 749f54d..8473b5a 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,12 @@ -This repository automates the build of QGIS and QGIS server Docker images. +# QGIS Docker -## QGIS Desktop standalone +This repository automates the build of QGIS desktop and QGIS server Docker images. -A simple QGIS desktop Docker image - - -## QGIS 3 server via Docker +## QGIS server ### General information -The Docker image is built using *Ubuntu 20.04 (focal) and 22.04 (jammy)* and official QGIS DEBs from https://qgis.org/. +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 @@ -22,7 +19,7 @@ Known good configurations are: - CentOS 8 - Fedora 29+ -See https://github.com/qgis/qgis-docker/issues/1 for further details. +See for further details. Containers are not tested on hosts running OSes other than Linux. @@ -35,38 +32,33 @@ A sample Nginx configuration for using it as a *FastCGI* backend is also [provid Image name: `qgis/qgis-server` -### QGIS stable -- `stable` | `stable-ubuntu` - -### QGIS LTR -- `ltr` | `ltr-ubuntu` +- **QGIS stable**: `stable` | `stable-ubuntu` +- **QGIS LTR**: `ltr` | `ltr-ubuntu` Example: -```bash -$ docker pull qgis/qgis-server:ltr +```sh +docker pull qgis/qgis-server:ltr ``` ### Build the container -#### QGIS stable - -```bash -$ docker build -t qgis/qgis-server:stable . -``` +#### QGIS stable -#### QGIS LTR +```sh +# stable version +docker build -t qgis/qgis-server:stable . -```bash -$ docker build --build-arg repo=ubuntu-ltr -t qgis/qgis-server:ltr . +# 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 -``` -$ docker run -v $(pwd)/data:/io/data --name qgis-server -d -p 8010:80 qgis/qgis-server:ltr +```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/`. @@ -78,7 +70,8 @@ Direct access to `WFS3` is accessible via `http://localhost:8010/wfs3/`. 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 ``` @@ -87,33 +80,20 @@ To use a pg_service file you need to bind mount it as shown in the [docker-compo 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 -``` +- 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: -``` -$ 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 openquake/qgis-server:ltr + +```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 -``` -$ docker exec -ti qgis-server /bin/bash +```sh +docker exec -ti qgis-server /bin/bash ``` where `qgis-server` is the name of the container. @@ -122,27 +102,27 @@ where `qgis-server` is the name of the container. QGIS server log can retreived via `docker logs` -``` -$ docker logs [-f] qgis-server +```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: -``` -$ 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 openquake/qgis-server:ltr +```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 the docker and map host data (via docker-compose) +### 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: -``` -$ docker-compose up -d --scale qgis-server=N +```sh +docker-compose up -d --scale qgis-server=N ``` Where N is the number of expected QGIS server workers. @@ -152,8 +132,8 @@ Where N is the number of expected QGIS server workers. `$(pwd)/data` must have the following structure: -``` -data +```text +data | |-- |-- .qgs @@ -163,7 +143,7 @@ data `$(pwd)/plugins` must have the following structure: -``` +```text plugins | |-- @@ -182,7 +162,7 @@ The following variables can be customized during container deployment: 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) +- `SKIP_NGINX`: default is *unset* (do not skip Nginx startup) #### QGIS @@ -200,9 +180,12 @@ It is also possible to customized the ID of the user running QGIS server process Example: `docker run -e QGIS_USER=1000` or `docker run -e QGIS_USER=$(id -u qgis)` - -## Notes +### 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 + +There is currently no documentation how to run the QGIS Desktop via docker.