Refactor variables

Author: valentinab25

docs/install/containers/images/backend.md

@@ -8,7 +8,7 @@ html_meta:
 
 # `plone/plone-backend`
 
-Plone backend [Docker](https://www.docker.com/) images using Python 3 and [pip](https://pip.pypa.io/en/stable/).
+Plone backend [Docker](https://www.docker.com/) images using Python 3 and [pip](https://pip.pypa.io/en/stable/) built on .
 
 
 ## Using this image
@@ -46,7 +46,14 @@ We encourage users of the `Plone` images to familiarize themselves with the opti
 | `DEFAULT_ZPUBLISHER_ENCODING` | `default-zpublisher-encoding` | `utf-8` |
 
 
-### Site creation
+### Site creation variables
+
+| Environment variable | Description |
+| --- | --- |
+| `SITE` | Id of the site to be created, for example, `Plone` |
+| `TYPE` | Type of the site, either `classic` or `volto`. Default: `volto` |
+| `PROFILES` | Initialize site with additional profiles, for example, `eea.api.layout:default` |
+| `DELETE_EXISTING` | Force site to be recreated if it already exists, for example, `true` |
 
 It is possible to initialize your database with a Plone Site instance on its first run.
 To do so, pass the `SITE` environment variable with the name of the Plone Site instance, for example, `SITE=Plone`.
@@ -67,21 +74,30 @@ Plone 6 Classic example:
 docker run -p 8080:8080 -e ADDONS="eea.facetednavigation" -e SITE="Plone" -e TYPE="classic" -e PROFILES="eea.facetednavigation:default" plone/plone-backend:6.0.0a4
 ```
 
-| Environment variable | Description |
-| --- | --- |
-| `SITE` | Id of the site to be created, for example, `Plone` |
-| `TYPE` | Type of the site, either `classic` or `volto`. Default: `volto` |
-| `PROFILES` | Initialize site with additional profiles, for example, `eea.api.layout:default` |
-| `DELETE_EXISTING` | Force site to be recreated if it already exists, for example, `true` |
-
 ```{warning}
 We advise against using this feature on production environments.
 ```
 
+### ZOPE variables
+
+| Environment variable | Description | Default value |
+| --- | --- | --- | --- |
+| `ZODB_CACHE_SIZE` | database cache size | `50000` |
+
+
+### ZEO variables
 
-### ZEO
+| Environment variable | Description | ZEO option | Default value |
+| --- | --- | --- | --- |
+| `ZEO_ADDRESS` | URL of the zeo interface, `host:port` |  |  |
+| `ZEO_SHARED_BLOB_DIR` | ZEO option |`name` | `off` |
+| `ZEO_READ_ONLY` | ZEO option |`read-only` | `false` |
+| `ZEO_CLIENT_READ_ONLY_FALLBACK` | ZEO option |`read-only-fallback` | `false` |
+| `ZEO_STORAGE` | ZEO option |`storage` | `1` |
+| `ZEO_CLIENT_CACHE_SIZE` | ZEO option | `cache-size` | `128MB` |
+| `ZEO_DROP_CACHE_RATHER_VERIFY` | ZEO option | `drop-cache-rather-verify` | `false` |
 
-To use a ZEO database, you need to pass the `ZEO_ADDRESS` to the image:
+#### Example
 
 ```yaml
 version: "3"
@@ -109,26 +125,44 @@ volumes:
   data: {}
 ```
 
-The following is a list of supported environment variables for ZEO:
 
-| Environment variable | ZEO option | Default value |
-| --- | --- | --- |
-| `ZEO_SHARED_BLOB_DIR` | `name` | `off` |
-| `ZEO_READ_ONLY` | `read-only` | `false` |
-| `ZEO_CLIENT_READ_ONLY_FALLBACK` | `read-only-fallback` | `false` |
-| `ZEO_STORAGE` | `storage` | `1` |
-| `ZEO_CLIENT_CACHE_SIZE` | `cache-size` | `128MB` |
-| `ZEO_DROP_CACHE_RATHER_VERIFY` | `drop-cache-rather-verify` | `false` |
+### Relational Database variables
+
 
+| Environment variable | Description | RelStorage option | Default value |
+| --- | --- | --- | --- |
+| `RELSTORAGE_DSN` | [PostgreSQL DSN](#postgresql-dsn) for the database interface | | |
+| `RELSTORAGE_NAME` | RelStorage option | `name` | `storage` |
+| `RELSTORAGE_READ_ONLY` | RelStorage option | `read-only` | `off` |
+| `RELSTORAGE_KEEP_HISTORY` | RelStorage option | `keep-history` | `true` |
+| `RELSTORAGE_COMMIT_LOCK_TIMEOUT` | RelStorage option | `commit-lock-timeout` | `30` |
+| `RELSTORAGE_CREATE_SCHEMA` | RelStorage option | `create-schema` | `true` |
+| `RELSTORAGE_SHARED_BLOB_DIR` | RelStorage option | `shared-blob-dir` | `false` |
+| `RELSTORAGE_BLOB_CACHE_SIZE` | RelStorage option | `blob-cache-size` | `100mb` |
+| `RELSTORAGE_BLOB_CACHE_SIZE_CHECK` | RelStorage option | `blob-cache-size-check` | `10` |
+| `RELSTORAGE_BLOB_CACHE_SIZE_CHECK_EXTERNAL` | RelStorage option | `blob-cache-size-check-external` | `false` |
+| `RELSTORAGE_BLOB_CHUNK_SIZE` | RelStorage option | `blob-chunk-size` | `1048576` |
+| `RELSTORAGE_CACHE_LOCAL_MB` | RelStorage option | `cache-local-mb` | `10` |
+| `RELSTORAGE_CACHE_LOCAL_OBJECT_MAX` | RelStorage option | `cache-local-object-max` | `16384` |
+| `RELSTORAGE_CACHE_LOCAL_COMPRESSION` | RelStorage option | `cache-local-compression` | `none` |
+| `RELSTORAGE_CACHE_DELTA_SIZE_LIMIT` | RelStorage option | `cache-delta-size-limit` | `100000` |
 
-### Relational Database
 
 ```{note}
 Currently this image supports only the configuration of a PostgreSQL backend via configuration variables.
 If you need to use MySQL or Oracle, we recommend that you extend this image and overwrite the `/app/etc/relstorage.conf` file.
 ```
 
-To use a PostgreSQL database, you need to pass the `RELSTORAGE_DSN` to the image:
+#### PostgreSQL DSN
+
+A valid PostgreSQL DSN is a list of parameters separated with whitespace.
+A typical DSN looks like the following:
+
+```console
+dbname='zodb' user='username' host='localhost' password='pass'
+```
+
+#### Example
 
 ```yaml
 version: "3"
@@ -154,34 +188,7 @@ services:
 
 ```
 
-A valid PostgreSQL DSN is a list of parameters separated with whitespace.
-A typical DSN looks like the following.
-
-```console
-dbname='zodb' user='username' host='localhost' password='pass'
-```
-
-The following is a list of supported environment variables for Relstorage:
-
-| Environment variable | RelStorage option | Default value |
-| --- | --- | --- |
-| `RELSTORAGE_NAME` | `name` | `storage` |
-| `RELSTORAGE_READ_ONLY` | `read-only` | `off` |
-| `RELSTORAGE_KEEP_HISTORY` | `keep-history` | `true` |
-| `RELSTORAGE_COMMIT_LOCK_TIMEOUT` | `commit-lock-timeout` | `30` |
-| `RELSTORAGE_CREATE_SCHEMA` | `create-schema` | `true` |
-| `RELSTORAGE_SHARED_BLOB_DIR` | `shared-blob-dir` | `false` |
-| `RELSTORAGE_BLOB_CACHE_SIZE` | `blob-cache-size` | `100mb` |
-| `RELSTORAGE_BLOB_CACHE_SIZE_CHECK` | `blob-cache-size-check` | `10` |
-| `RELSTORAGE_BLOB_CACHE_SIZE_CHECK_EXTERNAL` | `blob-cache-size-check-external` | `false` |
-| `RELSTORAGE_BLOB_CHUNK_SIZE` | `blob-chunk-size` | `1048576` |
-| `RELSTORAGE_CACHE_LOCAL_MB` | `cache-local-mb` | `10` |
-| `RELSTORAGE_CACHE_LOCAL_OBJECT_MAX` | `cache-local-object-max` | `16384` |
-| `RELSTORAGE_CACHE_LOCAL_COMPRESSION` | `cache-local-compression` | `none` |
-| `RELSTORAGE_CACHE_DELTA_SIZE_LIMIT` | `cache-delta-size-limit` | `100000` |
-
-
-### CORS
+### CORS variables
 
 | Environment variable | Description | Default value |
 | --- | --- | --- |
@@ -192,8 +199,18 @@ The following is a list of supported environment variables for Relstorage:
 | `CORS_ALLOW_HEADERS` | A comma separated list of request headers allowed to be sent by the client, for example `X-My-Header` | `Accept,Authorization,Content-Type,X-Custom-Header` |
 | `CORS_MAX_AGE` | Indicates how long the results of a preflight request can be cached | `3600` |
 
+Used to configure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+
+### Add-on variables
 
-### Add-on installation
+| Environment variable | Description | Details |
+| --- | --- | --- |
+| `ADDONS` | A space separated list of python libraries to install | [Add-ons](#add-ons) |
+| `DEVELOP` | A space separated list of python libraries to install in editable mode | [Developing packages](#developing-packages) |
+| `PIP_PARAMS` | Parameters used in `pip` installation commands | |
+
+
+#### Add-ons
 
 It is possible to install add-ons during startup time in a container created using this image.
 To do so, pass the `ADDONS` environment variable with a space separated list of requirements to be added to the image:
@@ -214,7 +231,7 @@ In this case, extend the image as explained before.
 ```
 
 
-### Developing packages
+#### Developing packages
 
 It is possible to install local packages instead of packages from pip.
 To do so, pass the `DEVELOP` environment variable with a space separated list of paths to Python packages to be installed.
@@ -235,14 +252,17 @@ We advise against using this feature on production environments.
 ```
 
 
+
 ## Extending from this image
 
 In a directory create a  `Dockerfile` file:
 
 ```Dockerfile
 FROM plone/plone-backend:6.0.0a4
 
-RUN ./bin/pip install "pas.plugin.authomatic"
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends gcc \
+    && rm -rf /var/lib/apt/lists/*
 ```
 
 Build your new image.
@@ -280,57 +300,7 @@ error: [Errno 13] Permission denied: '/app/lib/python3.9/site-packages/eea'
 
 ### Multiple containers with ZEO
 
-This image supports ZEO clusters as a simple way to allow horizontal scaling of the backend.
-To use it, 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.
-HAProxy is used for load balancing in this example.
-
-```yaml
-version: "3"
-services:
-
-  lb:
-    image: plone/plone-haproxy
-    depends_on:
-    - backend
-    ports:
-    - "8080:8080"
-    - "1936:1936"
-    environment:
-      FRONTEND_PORT: "8080"
-      BACKENDS: "backend"
-      BACKENDS_PORT: "8080"
-      DNS_ENABLED: "True"
-      HTTPCHK: "GET /"
-      INTER: "5s"
-      LOG_LEVEL: "info"
-
-  backend:
-    image: plone/plone-backend:6.0.0a4
-    restart: always
-    environment:
-      ZEO_ADDRESS: zeo:8100
-    ports:
-    - "8080"
-    depends_on:
-      - zeo
-
-  zeo:
-    image: plone/plone-zeo:latest
-    restart: always
-    volumes:
-      - data:/data
-    ports:
-    - "8100"
-
-volumes:
-  data: {}
-```
-
-Now run `docker-compose up -d --scale backend=4` from your project directory.
-
-Point your browser at `http://localhost:8080`, using the username and password combination of `admin` and `admin`, and you should see the default Plone site creation page.
-
-Point your browser at `http://localhost:1936`, using the username and password combination of `admin` and `admin`, and you should see HAProxy statistics for your Plone cluster.
+This image supports ZEO clusters as a simple way to allow horizontal scaling of the backend. Check the example page: {doc}`/volto/configuration/environmentvariables`.
 
 
 ## Versions