plone · ericof · Sep 15, 2026 · Sep 12, 2026 · Sep 12, 2026 · Sep 12, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 # Dependencies
+/.venv
 /venv
 
 # Generated files

diff --git a/docs/conf.py b/docs/conf.py
@@ -4,6 +4,7 @@
 
 # -- Path setup --------------------------------------------------------------
 
+import re
 from datetime import datetime
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -316,6 +317,17 @@
     "substitution",  # Use Jinja2 for substitutions. https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2
 ]
 
+# Versions of the container images used in the documentation.
+# Use them as MyST substitutions in text, such as {{PLONE_BACKEND_MINOR_VERSION}},
+# and as source replacements in code blocks, such as {PLONE_BACKEND_MINOR_VERSION}.
+container_image_versions = {
+    "PLONE_BACKEND_MINOR_VERSION": "6.2",
+    "PLONE_FRONTEND_VERSION": "19",
+    "PLONE_ZEO_VERSION": "6",
+    "TRAEFIK_VERSION": "v3.7",
+    "POSTGRES_VERSION": "18",
+}
+
 myst_substitutions = {
     "postman_basic_auth": "![](../_static/img/postman_basic_auth.png)",
     "postman_headers": "![](../_static/img/postman_headers.png)",
@@ -326,6 +338,7 @@
     "SUPPORTED_PYTHON_VERSIONS_PLONE60": "3.9, 3.10, 3.11, 3.12, or 3.13",
     "SUPPORTED_PYTHON_VERSIONS_PLONE61": "3.10, 3.11, 3.12, or 3.13",
     "SUPPORTED_PYTHON_VERSIONS_PLONE62": "3.10, 3.11, 3.12, 3.13, or 3.14",
+    **container_image_versions,
 }
 
 
@@ -467,14 +480,16 @@
 # https://stackoverflow.com/a/56328457/2214933
 def source_replace(app, docname, source):
     result = source[0]
-    for key in app.config.source_replacements:
-        result = result.replace(key, app.config.source_replacements[key])
+    for key, value in app.config.source_replacements.items():
+        # Skip MyST substitutions, such as {{KEY}}, which contain the key {KEY}.
+        pattern = rf"(?<!\{{){re.escape(key)}(?!\}})"
+        result = re.sub(pattern, lambda match, value=value: value, result)
     source[0] = result
 
 
-# Dict of replacements.
+# Dict of replacements, such as {PLONE_BACKEND_MINOR_VERSION}.
 source_replacements = {
-    "{PLONE_BACKEND_MINOR_VERSION}": "6.2",
+    f"{{{key}}}": value for key, value in container_image_versions.items()
 }
 
 

diff --git a/.../containers/examples/haproxy-plone-zeo.md → ...ers/examples/compose/haproxy-plone-zeo.md b/.../containers/examples/haproxy-plone-zeo.md → ...ers/examples/compose/haproxy-plone-zeo.md
@@ -1,8 +1,8 @@
 ---
 myst:
   html_meta:
-    "description": "Simple Plone 6 setup with scalable backend and data being persisted in a ZEO volume."
-    "property=og:description": "Simple Plone 6 setup with scalable backend and data being persisted in a ZEO volume."
+    "description": "HAProxy, a ZEO server, and one or more backend instances in a Plone 6 project for Docker Compose, with data persisted in a Docker volume."
+    "property=og:description": "HAProxy, a ZEO server, and one or more backend instances in a Plone 6 project for Docker Compose, with data persisted in a Docker volume."
     "property=og:title": "HAProxy, Backend, ZEO container example"
     "keywords": "Plone 6, Container, Docker, HAProxy, ZEO"
 ---
@@ -17,10 +17,9 @@ We will use the image [`plone/plone-haproxy`](https://github.com/plone/plone-hap
 
 ## Setup
 
-Create a directory for your project, and inside it create a `docker-compose.yml` file that starts your Plone instance and the ZEO instance with volume mounts for data persistence.
+Create a directory for your project, and inside it create a {file}`docker-compose.yml` file that starts your Plone instance and the ZEO instance with volume mounts for data persistence.
 
 ```yaml
-version: "3"
 services:
 
   lb:
@@ -40,7 +39,7 @@ services:
       LOG_LEVEL: "info"
 
   backend:
-    image: plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION}
+    image: plone/plone-backend:${STACK_BACKEND_TAG:?Set STACK_BACKEND_TAG}
     restart: always
     environment:
       ZEO_ADDRESS: zeo:8100
@@ -50,15 +49,32 @@ services:
       - zeo
 
   zeo:
-    image: plone/plone-zeo:latest
+    image: plone/plone-zeo:${STACK_ZEO_TAG:?Set STACK_ZEO_TAG}
     restart: always
     volumes:
-      - data:/data
-    ports:
-    - "8100"
+      - vol-site-data:/data
 
 volumes:
-  data: {}
+  vol-site-data: {}
+```
+
+
+### Environment variables
+
+The {file}`docker-compose.yml` file reads the tags of its images from the following environment variables.
+All of them are required, and `docker compose` stops with an error if one of them is missing.
+
+| Variable | Description | Default value | Example |
+| --- | --- | --- | --- |
+| `STACK_BACKEND_TAG` | Tag (version) of the image for the backend | | {{PLONE_BACKEND_MINOR_VERSION}} |
+| `STACK_ZEO_TAG` | Tag (version) of the image for the ZEO server | | {{PLONE_ZEO_VERSION}} |
+
+Create a {file}`.env` file in your project directory with your values.
+Docker Compose reads it automatically when you run `docker compose` from that directory.
+
+```shell
+STACK_BACKEND_TAG={PLONE_BACKEND_MINOR_VERSION}
+STACK_ZEO_TAG={PLONE_ZEO_VERSION}
 ```
 
 

diff --git a/docs/install/containers/examples/compose/index.md b/docs/install/containers/examples/compose/index.md
@@ -0,0 +1,53 @@
+---
+myst:
+  html_meta:
+    "description": "Docker Compose projects that run Plone 6 behind Traefik, nginx, or HAProxy."
+    "property=og:description": "Docker Compose projects that run Plone 6 behind Traefik, nginx, or HAProxy."
+    "property=og:title": "Docker Compose examples"
+    "keywords": "Plone 6, install, installation, Docker, Docker Compose, containers"
+---
+
+# Docker Compose examples
+
+```{toctree}
+:maxdepth: 2
+:hidden: true
+
+traefik-volto-plone
+traefik-volto-plone-zeo
+traefik-volto-plone-postgresql
+traefik-plone
+traefik-volto-plone-varnish
+nginx-volto-plone
+nginx-volto-plone-zeo
+nginx-volto-plone-postgresql
+nginx-plone
+haproxy-plone-zeo
+```
+
+Examples of projects running Plone using `docker compose`.
+
+## Traefik
+
+| Project example | Description |
+| --- | --- |
+| {doc}`traefik-volto-plone <traefik-volto-plone>` | Stack with Traefik, Frontend, and Backend |
+| {doc}`traefik-volto-plone-zeo <traefik-volto-plone-zeo>` | Stack with Traefik, Frontend, Backend, and ZEO server |
+| {doc}`traefik-volto-plone-postgresql <traefik-volto-plone-postgresql>` | Stack with Traefik, Frontend, Backend, and PostgreSQL DB |
+| {doc}`traefik-plone <traefik-plone>` | Stack with Traefik and Backend (Plone Classic) |
+| {doc}`traefik-volto-plone-varnish <traefik-volto-plone-varnish>` | Stack with Traefik, Frontend, Backend, ZEO server, and Varnish |
+
+## nginx
+
+| Project example | Description |
+| --- | --- |
+| {doc}`nginx-volto-plone <nginx-volto-plone>` | Stack with nginx, Frontend, and Backend |
+| {doc}`nginx-volto-plone-zeo <nginx-volto-plone-zeo>` | Stack with nginx, Frontend, Backend, and ZEO server |
+| {doc}`nginx-volto-plone-postgresql <nginx-volto-plone-postgresql>` | Stack with nginx, Frontend, Backend, and PostgreSQL DB |
+| {doc}`nginx-plone <nginx-plone>` | Stack with nginx and Backend (Plone Classic) |
+
+## HAProxy
+
+| Project example | Description |
+| --- | --- |
+| {doc}`haproxy-plone-zeo <haproxy-plone-zeo>` | Stack with HAProxy, Backend, and ZEO server |
diff --git a/...nstall/containers/examples/nginx-plone.md → ...ontainers/examples/compose/nginx-plone.md b/...nstall/containers/examples/nginx-plone.md → ...ontainers/examples/compose/nginx-plone.md
@@ -1,8 +1,8 @@
 ---
 myst:
   html_meta:
-    "description": "Simple Plone 6 setup with one backend and data being persisted in a Docker volume."
-    "property=og:description": "Simple Plone 6 setup with one backend and data being persisted in a Docker volume."
+    "description": "nginx and a Classic UI backend in a Plone 6 project for Docker Compose, with data persisted in a Docker volume."
+    "property=og:description": "nginx and a Classic UI backend in a Plone 6 project for Docker Compose, with data persisted in a Docker volume."
     "property=og:title": "nginx, Plone Classic container example"
     "keywords": "Plone 6, Container, Docker, nginx, Plone Classic"
 ---
@@ -16,7 +16,7 @@ This example is a simple setup with one backend and data being persisted in a Do
 
 ## Setup
 
-Create an empty project directory named `nginx-plone`.
+Create an empty project directory named {file}`nginx-plone`.
 
 ```shell
 mkdir nginx-plone
@@ -31,7 +31,7 @@ cd nginx-plone
 
 ### nginx configuration
 
-Add a `default.conf` that will be used by the nginx image:
+Add a {file}`default.conf` that will be used by the nginx image:
 
 ```nginx
 upstream backend {
@@ -61,12 +61,12 @@ server {
 
 ```{note}
 `http://plone.localhost/` is the URL you will be using to access the website.
-You can either use `plone.localhost`, or add it in your `/etc/hosts` file or DNS, to point to the Docker host IP.
+You can either use `plone.localhost`, or add it in your {file}`/etc/hosts` file or DNS, to point to the Docker host IP.
 ```
 
 ### Service configuration with Docker Compose
 
-Now let's create a `docker-compose.yml` file:
+Now let's create a {file}`docker-compose.yml` file:
 
 ```yaml
 services:
@@ -81,17 +81,34 @@ services:
     - "80:80"
 
   backend:
-    image: plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION}
+    image: plone/plone-backend:${STACK_BACKEND_TAG:?Set STACK_BACKEND_TAG}
     environment:
       SITE: Plone
       TYPE: classic
     volumes:
-      - data:/data
+      - vol-site-data:/data
     ports:
     - "8080:8080"
 
 volumes:
-  data: {}
+  vol-site-data: {}
+```
+
+
+### Environment variables
+
+The {file}`docker-compose.yml` file reads the tags of its images from the following environment variables.
+All of them are required, and `docker compose` stops with an error if one of them is missing.
+
+| Variable | Description | Default value | Example |
+| --- | --- | --- | --- |
+| `STACK_BACKEND_TAG` | Tag (version) of the image for the backend | | {{PLONE_BACKEND_MINOR_VERSION}} |
+
+Create a {file}`.env` file in your project directory with your values.
+Docker Compose reads it automatically when you run `docker compose` from that directory.
+
+```shell
+STACK_BACKEND_TAG={PLONE_BACKEND_MINOR_VERSION}
 ```
 
 

diff --git a/.../examples/nginx-volto-plone-postgresql.md → ...s/compose/nginx-volto-plone-postgresql.md b/.../examples/nginx-volto-plone-postgresql.md → ...s/compose/nginx-volto-plone-postgresql.md
@@ -1,22 +1,22 @@
 ---
 myst:
   html_meta:
-    "description": "Very simple Plone 6 setup with only one or more backend instances accessing a PostgreSQL server and data being persisted in a Docker volume."
-    "property=og:description": "Very simple Plone 6 setup with only one or more backend instances accessing a PostgreSQL server and data being persisted in a Docker volume."
+    "description": "PostgreSQL server, nginx, a frontend, and one or more backend instances in a Plone 6 project for Docker Compose, with data persisted in a Docker volume."
+    "property=og:description": "PostgreSQL server, nginx, a frontend, and one or more backend instances in a Plone 6 project for Docker Compose, with data persisted in a Docker volume."
     "property=og:title": "nginx, Frontend, Backend, PostgreSQL container example"
-    "keywords": "Plone 6, Container, Docker, nginx, Frontend, Backend, PostgreSQL, "
+    "keywords": "Plone 6, Container, Docker, nginx, Frontend, Backend, PostgreSQL"
 ---
 
 # nginx, Frontend, Backend, PostgreSQL container example
 
-This example is a very simple setup with one or more backend instances accessing a Postgres server and data being persisted in a Docker volume.
+This example is a very simple setup with one or more backend instances accessing a PostgreSQL server and data being persisted in a Docker volume.
 
 {term}`nginx` in this example is used as a [reverse proxy](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/).
 
 
 ## Setup
 
-Create an empty project directory named `nginx-volto-plone-postgresql`.
+Create an empty project directory named {file}`nginx-volto-plone-postgresql`.
 
 ```shell
 mkdir nginx-volto-plone-postgresql
@@ -31,7 +31,7 @@ cd nginx-volto-plone-postgresql
 
 ### nginx configuration
 
-Add a `default.conf` that will be used by the nginx image:
+Add a {file}`default.conf` that will be used by the nginx image:
 
 ```nginx
 upstream backend {
@@ -74,13 +74,13 @@ server {
 
 ```{note}
 `http://plone.localhost/` is the URL you will be using to access the website.
-You can either use `localhost`, or add it in your `/etc/hosts` file or DNS to point to the Docker host IP.
+You can either use `localhost`, or add it in your {file}`/etc/hosts` file or DNS to point to the Docker host IP.
 ```
 
 
 ### Service configuration with Docker Compose
 
-Now let's create a `docker-compose.yml` file:
+Now let's create a {file}`docker-compose.yml` file:
 
 ```yaml
 services:
@@ -96,7 +96,7 @@ services:
     - "80:80"
 
   frontend:
-    image: plone/plone-frontend:latest
+    image: plone/plone-frontend:${STACK_FRONTEND_TAG:?Set STACK_FRONTEND_TAG}
     environment:
       RAZZLE_INTERNAL_API_PATH: http://backend:8080/Plone
     ports:
@@ -105,7 +105,7 @@ services:
       - backend
 
   backend:
-    image: plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION}
+    image: plone/plone-backend:${STACK_BACKEND_TAG:?Set STACK_BACKEND_TAG}
     environment:
       SITE: Plone
       RELSTORAGE_DSN: "dbname='plone' user='plone' host='db' password='plone'"
@@ -115,18 +115,37 @@ services:
       - db
 
   db:
-    image: postgres
+    image: postgres:${STACK_POSTGRES_TAG:?Set STACK_POSTGRES_TAG}
     environment:
       POSTGRES_USER: plone
       POSTGRES_PASSWORD: plone
       POSTGRES_DB: plone
     volumes:
-    - data:/var/lib/postgresql/data
-    ports:
-    - "5432:5432"
+    - vol-site-data:/var/lib/postgresql
 
 volumes:
-  data: {}
+  vol-site-data: {}
+```
+
+
+### Environment variables
+
+The {file}`docker-compose.yml` file reads the tags of its images from the following environment variables.
+All of them are required, and `docker compose` stops with an error if one of them is missing.
+
+| Variable | Description | Default value | Example |
+| --- | --- | --- | --- |
+| `STACK_FRONTEND_TAG` | Tag (version) of the image for the frontend | | {{PLONE_FRONTEND_VERSION}} |
+| `STACK_BACKEND_TAG` | Tag (version) of the image for the backend | | {{PLONE_BACKEND_MINOR_VERSION}} |
+| `STACK_POSTGRES_TAG` | Tag (version) of the image for PostgreSQL | | {{POSTGRES_VERSION}} |
+
+Create a {file}`.env` file in your project directory with your values.
+Docker Compose reads it automatically when you run `docker compose` from that directory.
+
+```shell
+STACK_FRONTEND_TAG={PLONE_FRONTEND_VERSION}
+STACK_BACKEND_TAG={PLONE_BACKEND_MINOR_VERSION}
+STACK_POSTGRES_TAG={POSTGRES_VERSION}
 ```