ibexa · mnocon · Dec 16, 2025 · Dec 16, 2025 · Dec 17, 2025 · Jan 20, 2026
diff --git a/docs/administration/project_organization/bundles.md b/docs/administration/project_organization/bundles.md
@@ -54,7 +54,8 @@
 |[ibexa/http-cache](https://github.com/ibexa/http-cache)|[HTTP cache handling](http_cache.md), using multi tagging|
 |[ibexa/i18n](https://github.com/ibexa/i18n)|Centralized translations to ease synchronization with Crowdin|
 |[ibexa/notifications](https://github.com/ibexa/notifications)| Sending [notifications](notifications.md)|
-|[ibexa/post-install](https://github.com/ibexa/post-install)|Post installation tool|
+|[ibexa/cloud](https://github.com/ibexa/cloud)|(Optional) [[= product_name_cloud =]] integration package|
+|[ibexa/post-install](https://github.com/ibexa/post-install)|Bundle containing Apache and nginx templates|
 |[ibexa/rest](https://github.com/ibexa/rest)|REST API|
 |[ibexa/search](https://github.com/ibexa/search)|Common search functionalities|
 |[ibexa/solr](https://github.com/ibexa/solr)|[Solr-powered](https://solr.apache.org/) search handler|

diff --git a/docs/getting_started/install_ibexa_dxp.md b/docs/getting_started/install_ibexa_dxp.md
@@ -147,13 +147,15 @@ To use Composer to instantly create a project in the current folder with all the
 
 !!! note "[[= product_name_cloud =]]"
 
-    If you're deploying your installation on [Upsun](https://fixed.docs.upsun.com/guides/ibexa/deploy.html), run the following command:
+    If you're deploying your installation on [Upsun](https://fixed.docs.upsun.com/guides/ibexa/deploy.html), run the following commands:
 
     ``` bash
-    composer ibexa:setup --platformsh
+    composer require ibexa/cloud
+    php bin/console ibexa:cloud:setup --upsun
     ```
 
-    This command provides the necessary configuration for using [[= product_name_cloud =]].
+    These commands add the necessary package and provide the required configuration for using Upsun.
+    For more information, see [Install on Ibexa Cloud](install_on_ibexa_cloud.md).
 
 #### Add project to version control
 

diff --git a/docs/ibexa_cloud/environment_variables.md b/docs/ibexa_cloud/environment_variables.md
@@ -0,0 +1,147 @@
+---
+description: Environment variables automatically generated based on Ibexa Cloud relationships and routes.
+---
+
+# Environment variables on Ibexa Cloud
+
+[[= product_name_cloud =]] automatically generates environment variables based on the Upsun relationships and routes configuration.
+It parses `PLATFORM_RELATIONSHIPS` and `PLATFORM_ROUTES` environment variables and exposes them as application-specific variables.
+
+Environment variable prefixes are created by converting relationship names to uppercase and replacing hyphens with underscores.
+
+When multiple endpoints are defined for a single relationship, numerical indices are used for all entries except the first one, for example: `SOLR`, `SOLR_1_`, `SOLR_2`.
+When multiple services of the same type are present, environment variables are exposed for each service accordingly based on their relationship names.
+
+## Using environment variables in configuration files
+
+If you're referencing [[= product_name_cloud =]] environment variables in your configuration files, you must define placeholder values for them in your `.env` file to prevent Symfony container initialization failures.
+
+Do it only for the variables that are required for the Symfony container to build.
+
+For example, if your `doctrine.yaml` uses a [database variable](#database-variables) created for a relationship named `pgsql`:
+
+``` yaml
+doctrine:
+    dbal:
+        url: '%env(resolve:PGSQL_URL)%'
+```
+
+You must define a placeholder value in `.env`:
+
+``` env
+PGSQL_URL="postgresql://app:!ChangeMe!@127.0.0.1:5432/app?serverVersion=16&charset=utf8"
+```
+
+The actual value of the environment variable is provided by [[= product_name_cloud =]] at runtime.
+The placeholder in `.env` is only required to prevent Symfony container compilation errors during build.
+
+## Relationship naming conventions
+
+You can choose relationship names freely in `.platform.app.yaml` for most services.
+
+The only required names are:
+
+- `dfs_database` - DFS database (required for DFS functionality)
+- `redissession` or `valkeysession` - Redis/Valkey for sessions (required for dedicated session storage)
+
+Common relationship name include:
+
+- `database` - main application database
+- `rediscache` - Redis for cache
+- `elasticsearch` - Elasticsearch search service
+- `solr` - Solr search service
+
+## Database variables
+
+For MySQL and PostgreSQL databases, the following variables are generated based on the relationship name (e.g., `database`):
+
+- `{RELATIONSHIP_NAME}_URL` - full database URL with charset and server version
+- `{RELATIONSHIP_NAME}_USER` / `{RELATIONSHIP_NAME}_USERNAME` - database user
+- `{RELATIONSHIP_NAME}_PASSWORD` - database password
+- `{RELATIONSHIP_NAME}_HOST` - database host
+- `{RELATIONSHIP_NAME}_PORT` - database port
+- `{RELATIONSHIP_NAME}_NAME` / `{RELATIONSHIP_NAME}_DATABASE` - database name
+- `{RELATIONSHIP_NAME}_DRIVER` - database driver
+- `{RELATIONSHIP_NAME}_SERVER` - database server
+
+For example, for a relationship called `database` the environment variables are named `DATABASE_URL`, `DATABASE_HOST`, `DATABASE_USER`, etc.
+
+For more information about database configuration, see [Databases](databases.md).
+
+## DFS database variables
+
+When using [distributed file storage (DFS) using a separate database](clustering.md#dfs-io-handler), you must use the relationship name `dfs_database`.
+In addition to the database variables listed above, additional DFS-specific variables are created when `PLATFORMSH_DFS_NFS_PATH` is set:
+
+- `DFS_NFS_PATH` - NFS path for DFS storage
+- `DFS_DATABASE_CHARSET` - database character set
+- `DFS_DATABASE_COLLATION` - database collation
+
+## Cache variables
+
+For Redis, Valkey, and Memcached cache services, the following variables are available.
+
+- `{RELATIONSHIP_NAME}_URL` (Redis/Valkey only)
+- `{RELATIONSHIP_NAME}_HOST`
+- `{RELATIONSHIP_NAME}_PORT`
+- `{RELATIONSHIP_NAME}_SCHEME` (Redis/Valkey only)
+
+In addition, the following global variables are defined:
+
+- `CACHE_POOL` - either `cache.redis` or `cache.memcached`
+- `CACHE_DSN` - cache connection string
+
+!!! note
+    Redis/Valkey services have higher priority than Memcached services when building the global cache variables.
+
+For more information about persistence cache configuration, see [Persistence cache](persistence_cache.md).
+
+## Session variables
+
+For Redis-based session storage, the following variables are available.
+
+- `SESSION_HANDLER_ID` - session handler class name
+- `SESSION_SAVE_PATH` - Redis connection in `host:port` format
+
+The system looks for a relationships named `redissession` or `valkeysession` first.
+If not found, it uses the first available Redis-compatible service.
+
+For more information about session configuration, see [Sessions](sessions.md).
+
+## Search engine variables
+
+### Solr
+
+For Solr search engine configuration, the following variables are generated:
+
+- `SEARCH_ENGINE` - set to `solr`
+- `SOLR_DSN` - Solr connection string
+- `SOLR_CORE` - Solr core name
+- `{RELATIONSHIP_NAME}_HOST`
+- `{RELATIONSHIP_NAME}_PORT`
+- `{RELATIONSHIP_NAME}_NAME` / `{RELATIONSHIP_NAME}_DATABASE`
+
+For more information, see [Solr search engine](solr_overview.md).
+
+### Elasticsearch
+
+For Elasticsearch search engine configuration, the following variables are generated:
+
+- `SEARCH_ENGINE` - set to `elasticsearch`
+- `ELASTICSEARCH_DSN` - Elasticsearch connection string
+- `{RELATIONSHIP_NAME}_URL`
+- `{RELATIONSHIP_NAME}_HOST`
+- `{RELATIONSHIP_NAME}_PORT`
+- `{RELATIONSHIP_NAME}_SCHEME`
+
+For more information, see [Elasticsearch](elasticsearch_overview.md).
+
+## HTTP cache variables (Varnish)
+
+For Varnish-based HTTP caching, the following variables are available.
+
+- `HTTPCACHE_PURGE_TYPE` - set to `varnish`
+- `HTTPCACHE_PURGE_SERVER` - Varnish server address
+- `HTTPCACHE_VARNISH_INVALIDATE_TOKEN` - token for cache invalidation
+
+For more information about HTTP cache and Varnish configuration, see [HTTP cache](http_cache.md).
diff --git a/docs/ibexa_cloud/ibexa_cloud.md b/docs/ibexa_cloud/ibexa_cloud.md
@@ -11,5 +11,6 @@ month_change: false
 [[= cards([
     "ibexa_cloud/ibexa_cloud_guide",
     "ibexa_cloud/install_on_ibexa_cloud",
+    "ibexa_cloud/environment_variables",
     "ibexa_cloud/ddev_and_ibexa_cloud",
 ], columns=3) =]]
diff --git a/docs/ibexa_cloud/install_on_ibexa_cloud.md b/docs/ibexa_cloud/install_on_ibexa_cloud.md
@@ -9,13 +9,14 @@
 
 ## 1. Prepare configuration files
 
-If you didn't run the `composer ibexa:setup` command during installation, run it now:
+If you didn't add cloud configuration during installation, run the following commands now:
 
 ``` bash
-composer ibexa:setup --platformsh
+composer require ibexa/cloud
+php bin/console ibexa:cloud:setup --upsun
 ```
 
-This command adds to your project configuration files required for using [[= product_name_cloud =]].
+These commands add the necessary package and configuration files required for using [[= product_name_cloud =]].
 
 You can adapt the configuration in the following places:
 
@@ -49,6 +50,8 @@
 
 If you enable any of the services, you must uncomment the relevant relationship under the `relationship` key in `.platform.app.yaml` as well.
 
+For information about environment variables automatically generated based on your service configuration, see [Environment variables on [[= product_name_cloud =]]](environment_variables.md).
+
 ## 2. Create an account
 
 Log in to https://console.ibexa.cloud or create an account if you don't have one yet.

diff --git a/docs/infrastructure_and_maintenance/cache/persistence_cache.md b/docs/infrastructure_and_maintenance/cache/persistence_cache.md
@@ -159,7 +159,7 @@ Out of the box in `config/packages/cache_pool/cache.redis.yaml` you can find a d
 
 !!! note "[[= product_name_cloud =]]"
 
-    For [[= product_name_cloud =]]: This is automatically configured in `vendor/ibexa/core/src/bundle/Core/DependencyInjection/IbexaCoreExtension.php` if you have enabled Redis as `rediscache` Upsun service.
+    For [[= product_name_cloud =]], it's configured based on the `.platform.app.yaml` file by the [`ibexa/cloud` package](install_on_ibexa_cloud.md).
 
 For anything else, you can enable it with environment variables.
 For instance, if you set the following environment variables `export CACHE_POOL="cache.redis" CACHE_DSN="secret@example.com:1234/13"`, it results in config like this:

diff --git a/docs/infrastructure_and_maintenance/clustering/clustering.md b/docs/infrastructure_and_maintenance/clustering/clustering.md
@@ -136,18 +136,14 @@ For production, it's recommended to create the DFS table in its own database, ma
     CREATE INDEX ibexa_dfs_file_name_trunk ON ibexa_dfs_file USING btree (name_trunk);
     ```
 
-!!! note
-    On [[= product_name_cloud =]] a separate DFS database is supported for MySQL only.
-
 This example uses Doctrine connection named `dfs`:
 
 ``` yaml
 parameters:
     env(DFS_DATABASE_URL): '%env(resolve:DATABASE_URL)%'
-    dfs_nfs_path: '%env(resolve:DFS_NFS_PATH)%'
     dfs_database_url: '%env(resolve:DFS_DATABASE_URL)%'
     ibexa.io.nfs.adapter.config:
-        root: '%dfs_nfs_path%'
+        root: '%kernel.project_dir%/%env(string:DFS_NFS_PATH)%'
         path: '$var_dir$/$storage_dir$/'
         writeFlags: ~
         linkHandling: ~
@@ -159,12 +155,12 @@ doctrine:
         connections:
             dfs:
                 # configure these for your database server
-                driver: '%dfs_database_driver%'
-                charset: '%dfs_database_charset%'
+                driver: '%env(string:DFS_DATABASE_DRIVER)%'
+                charset: '%env(string:DFS_DATABASE_CHARSET)%'
                 default_table_options:
-                    charset: '%dfs_database_charset%'
-                    collate: '%dfs_database_collation%'
-                url: '%dfs_database_url%'
+                    charset: '%env(string:DFS_DATABASE_CHARSET)%'
+                    collate: '%env(string:DFS_DATABASE_COLLATION)%'
+                url: '%env(string:DFS_DATABASE_URL)%'
 
 # define the Flysystem handler
 oneup_flysystem:

diff --git a/docs/infrastructure_and_maintenance/sessions.md b/docs/infrastructure_and_maintenance/sessions.md
@@ -92,7 +92,7 @@ Alternatively if you have needs to configure the servers dynamically:
 
 !!! note "[[= product_name_cloud =]]"
 
-    For [[= product_name_cloud =]], this is already configured based on `.platform.app.yaml` config.
+    For [[= product_name_cloud =]], it's configured based on the `.platform.app.yaml` file by the [`ibexa/cloud` package](install_on_ibexa_cloud.md).
 
 If you're on `php-redis` v4.2.0 and higher, you can optionally tweak [`php-redis` settings](https://github.com/phpredis/phpredis#session-locking) for session locking.
 

diff --git a/docs/release_notes/ibexa_dxp_v5.0.md b/docs/release_notes/ibexa_dxp_v5.0.md
@@ -10,6 +10,27 @@ month_change: false
 
 <div class="release-notes" markdown="1">
 
+[[% set version = 'v5.0.6' %]]
+
+[[= release_note_entry_begin("Ibexa DXP " + version, '2025-XX-XX', ['Headless', 'Experience', 'Commerce', 'New feature']) =]]
+
+#### Ibexa Cloud improvements
+
+##### New cloud configuration package
+
+A new `ibexa/cloud` package is now available for [[= product_name_cloud =]] deployments.
+This package replaces the previous `composer ibexa:setup --platformsh` command with a dedicated console command.
+
+The package automatically generates environment variables based on [[= product_name_cloud =]] relationships and routes configuration, making it easier to configure services like databases, cache, search engines, and session storage.
+
+For more information, see [Install on Ibexa Cloud](install_on_ibexa_cloud.md) and [Environment variables on Ibexa Cloud](environment_variables.md).
+
+### Full changelog
+
+<!-- [[% include 'snippets/release_50.md' %]] -->
+
+[[= release_note_entry_end() =]]
+
 [[% set version = 'v5.0.5' %]]
 
 [[= release_note_entry_begin("Ibexa DXP " + version, '2026-01-15', ['Headless', 'Experience', 'Commerce']) =]]

diff --git a/docs/resources/new_in_doc.md b/docs/resources/new_in_doc.md
@@ -7,6 +7,17 @@
 
 This page contains recent highlights and notable changes in [[= product_name =]] documentation.
 
+## DRAFT 2026
+
+### Ibexa Cloud
+
+- Added documentation describing [how to use the new `ibexa/cloud` package](install_on_ibexa_cloud.md) and the [environment variables it provides]
+
+### Configuration
+
+- Updated [DFS](clustering.md#configuring-the-dfs-io-handler) and [Solr](install_solr.md#configure-the-bundle) configuration examples to use environment variables directly with [Environment Variable Processors]([[= symfony_doc =]]/configuration/env_var_processors.html) syntax instead of intermediate parameters.
+This promotes skipping rebuilding the Symfony container when environment variable values change.
+
 ## January 2026
 
 ### Releases

diff --git a/docs/search/search_engines/solr_search_engine/install_solr.md b/docs/search/search_engines/solr_search_engine/install_solr.md
@@ -183,8 +183,8 @@ Out of the box in [[= product_name =]] the following is enabled for a setup:
 ibexa_solr:
     endpoints:
         endpoint0:
-            dsn: '%solr_dsn%'
-            core: '%solr_core%'
+            dsn: '%env(string:SOLR_DSN)%'
+            core: '%env(string:SOLR_CORE)%'
     connections:
         default:
             entry_endpoints:
@@ -202,10 +202,10 @@ The installation contains several similar languages, and one different language
 ibexa_solr:
     endpoints:
         endpoint0:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core0
         endpoint1:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core1
     connections:
         default:
@@ -232,25 +232,25 @@ ibexa_solr:
     version: '9.8.1' # Required only if using Solr 9
     endpoints:
         endpoint0:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core0
         endpoint1:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core1
         endpoint2:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core2
         endpoint3:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core3
         endpoint4:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core4
         endpoint5:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core5
         endpoint6:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core6
     connections:
         default:
@@ -286,13 +286,13 @@ The example is based on multi-core setup so any specific language analysis optio
 ibexa_solr:
     endpoints:
         main:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: '%solr_main_core%'
         en:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: '%solr_en_core%'
         fr:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: '%solr_fr_core%'
         # ...
     connections:
@@ -325,7 +325,7 @@ In the example below we configured Solr Bundle to work with secured Solr core.
 ibexa_solr:
     endpoints:
         endpoint0:
-            dsn: '%solr_dsn%'
+            dsn: '%env(string:SOLR_DSN)%'
             core: core0
             user: example
             pass: password