Merge pull request #567 from benz0li/add-container-images-instructions

Add instructions for container images

config.toml

@@ -503,17 +503,23 @@ sectionPagesMenu = 'main'
     url = "/resources/installation-guide/#openbsd"
     weight = 220
 
+  [[menu.main]]
+    parent = "Installation guide"
+    name = "Container images"
+    url = "/resources/installation-guide/#container-images"
+    weight = 230
+
   [[menu.main]]
     parent = "Installation guide"
     name = "QGIS Testing warning"
     url = "/resources/installation-guide/#qgis-testing-warning"
-    weight = 230
+    weight = 240
 
   [[menu.main]]
     parent = "Installation guide"
     name = "Installing from Source"
     url = "/resources/installation-guide/#installing-from-source"
-    weight = 240
+    weight = 250
 
 [[menu.main]]
   parent = "Resources"

content/download/index.md

@@ -80,6 +80,10 @@ After installing QGIS, the first launch attempt may fail due to Apple's security
 [BSD Installation Instructions]({{< ref "resources/installation-guide#freebsd" >}})
 {{< spoiler-end >}}
 
+{{< spoiler-start id="download-container-images" title="🐳 Container Images" >}}
+[Container Images Installation Instructions]({{< ref "resources/installation-guide#container-images" >}})
+{{< spoiler-end >}}
+
 
 {{< spoiler-start id="download-mobile" title="📱Mobile and tablet" >}}
 {{< mobile-downloads >}}

content/resources/installation-guide/index.md

@@ -718,6 +718,118 @@ See:
 - https://openbsd.app/?search=qgis for -stable OpenBSD
 - https://openbsd.app/?search=qgis&current=on for -current OpenBSD
 
+# Container images
+
+(GPU accelerated) Multi-arch JupyterLab QGIS container images.
+
+- Current `os/arch`s: `linux/amd64`, `linux/arm64/v8`
+  - Run on Apple M series using
+    [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+  - or using [Podman Desktop](https://podman-desktop.io) (rootless mode).
+- Base images: [Debian](https://hub.docker.com/_/debian) and
+   [Ubuntu](https://hub.docker.com/_/ubuntu)
+  - GPU accelerated images are
+    [CUDA](https://hub.docker.com/r/nvidia/cuda)-based (Ubuntu).
+- [TurboVNC](https://turbovnc.org): High-speed VNC version
+  - CUDA-based images run [VirtualGL](https://virtualgl.org) to accelerate
+    OpenGL applications.
+- Just Python – no [Conda](https://github.com/conda/conda) /
+   [Mamba](https://github.com/mamba-org/mamba)
+
+{{< rich-box-start icon="🧑‍💻" layoutClass="tips">}}
+{{< rich-content-start themeClass="coloring-1" >}}
+##### Note
+
+`linux/arm64/v8` QGIS container images are known to crash randomly on Apple M
+series.
+
+GPU acceleration requires an NVIDIA GPU, the NVIDIA Linux driver and the NVIDIA
+Container Toolkit.
+{{< rich-content-end >}}
+{{< rich-box-end >}}
+
+For further information, see
+<https://github.com/b-data/jupyterlab-qgis-docker-stack>.
+
+## QGIS stable
+
+To run the container with the latest QGIS stable version, command
+
+```shell
+docker run -it --rm \
+  -p 8888:8888 \
+  -v jupyterlab-jovyan:/home/jovyan \
+  glcr.b-data.ch/jupyterlab/qgis/base
+```
+
+To run the GPU accelerated container with the latest QGIS stable version, command
+
+```shell
+docker run -it --rm \
+  --gpus 'device=all' \
+  -p 8888:8888 \
+  -v jupyterlab-jovyan:/home/jovyan \
+  glcr.b-data.ch/jupyterlab/cuda/qgis/base
+```
+
+## QGIS LTR
+
+To run the container with the latest QGIS LTR version, command
+
+```shell
+docker run -it --rm \
+  -p 8888:8888 \
+  -v jupyterlab-jovyan:/home/jovyan \
+  glcr.b-data.ch/jupyterlab/qgis/base:ltr
+```
+
+To run the GPU accelerated container with the latest QGIS LTR version, command
+
+```shell
+docker run -it --rm \
+  --gpus 'device=all' \
+  -p 8888:8888 \
+  -v jupyterlab-jovyan:/home/jovyan \
+  glcr.b-data.ch/jupyterlab/cuda/qgis/base:ltr
+```
+
+## QGIS version
+
+To run a container with a specific QGIS version, command
+
+```shell
+docker run -it --rm \
+  -p 8888:8888 \
+  -v jupyterlab-jovyan:/home/jovyan \
+  glcr.b-data.ch/jupyterlab/qgis/base:MAJOR[.MINOR[.PATCH]]
+```
+
+{{< rich-box-start icon="🐳" layoutClass="tips">}}
+{{< rich-content-start themeClass="coloring-1" >}}
+##### Note
+
+Container images are available for QGIS versions ≥ 3.28.4.
+{{< rich-content-end >}}
+{{< rich-box-end >}}
+
+To run a GPU accelerated container with a specific QGIS version, command
+
+```shell
+docker run -it --rm \
+  --gpus 'device=all' \
+  -p 8888:8888 \
+  -v jupyterlab-jovyan:/home/jovyan \
+  glcr.b-data.ch/jupyterlab/cuda/qgis/base:MAJOR[.MINOR[.PATCH]]
+```
+
+{{< rich-box-start icon="🔥" layoutClass="tips">}}
+{{< rich-content-start themeClass="coloring-1" >}}
+##### Note
+
+GPU accelerated container images are available for QGIS versions ≥ 3.34.0.
+{{< rich-content-end >}}
+{{< rich-box-end >}}
+
 # QGIS Testing warning
 
 {{< rich-box-start icon="⚠️" layoutClass="tips">}}

playwright/ci-test/tests/06-resources-page.spec.ts

@@ -90,6 +90,7 @@ test.describe("Resources pages", () => {
         await expect(sidebar.macOSLink).toBeVisible();
         await expect(sidebar.freeBSDLink).toBeVisible();
         await expect(sidebar.openBSDLink).toBeVisible();
+        await expect(sidebar.containerImagesLink).toBeVisible();
         await expect(sidebar.qgisTestingWarningLink).toBeVisible();
         await expect(sidebar.installingFromSourceLink).toBeVisible();
         await expect(

playwright/ci-test/tests/fixtures/installation-guide-page.ts

@@ -94,6 +94,7 @@ export class InstallationGuidePage {
         "QGIS LTR",
         "NixOS",
         "OpenBSD",
+        "Container images",
         "QGIS Testing warning",
         "Installing from Source",
     ];

playwright/ci-test/tests/fixtures/sidebar.ts

@@ -31,6 +31,7 @@ export class Sidebar {
     public readonly macOSLink: Locator;
     public readonly freeBSDLink: Locator;
     public readonly openBSDLink: Locator;
+    public readonly containerImagesLink: Locator;
     public readonly qgisTestingWarningLink: Locator;
     public readonly installingFromSourceLink: Locator;
 
@@ -113,6 +114,10 @@ export class Sidebar {
             name: "OpenBSD",
         });
 
+        this.containerImagesLink = this.sidebar.getByRole("link", {
+            name: "Container images",
+        });
+
         this.qgisTestingWarningLink = this.sidebar.getByRole("link", {
             name: "QGIS Testing Warning",
         });