diff --git a/docs/administration/project_organization/bundles.md b/docs/administration/project_organization/bundles.md index 7b7283bce0..44854dcc22 100644 --- a/docs/administration/project_organization/bundles.md +++ b/docs/administration/project_organization/bundles.md @@ -54,7 +54,8 @@ To remove a bundle (either one you created yourself, or an out-of-the-box one th |[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 index 54529d20bc..b4c9fc80e4 100644 --- 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 "Platform.sh" - If you're deploying your installation on [Platform.sh](https://docs.platform.sh/guides/ibexa/deploy.html), run the following command: + If you're deploying your installation on [Platform.sh](https://docs.platform.sh/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 Platform.sh. + These commands add the necessary package and provide the required configuration for using Platform.sh. + 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 new file mode 100644 index 0000000000..bcfe1fa93e --- /dev/null +++ b/docs/ibexa_cloud/environment_variables.md @@ -0,0 +1,116 @@ +--- +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 Platform.sh 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 example: `SOLR_1_`, `SOLR_2`. + +## Relationship naming conventions + +Use the following relationship names in `.platform.app.yaml`: + +- `database` - main application database +- `dfs_database` - DFS database (required name for DFS functionality) +- `rediscache` - Redis for cache +- `redissession` - Redis for sessions (recommended name for dedicated session storage) +- `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 and Memcached cache services, the following variables are available. + +- `{RELATIONSHIP_NAME}_URL` (Redis only) +- `{RELATIONSHIP_NAME}_HOST` +- `{RELATIONSHIP_NAME}_PORT` +- `{RELATIONSHIP_NAME}_SCHEME` (Redis only) + +In addition, the following global variables are defined: + +- `CACHE_POOL` - either `cache.redis` or `cache.memcached` +- `CACHE_DSN` - cache connection string + +!!! note + Redis 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 relationship named `redissession` first. If not found, it uses the first available Redis 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 index 2635127a5d..2cfb19367b 100644 --- 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 index 93a0ab4c49..4dc8c44f43 100644 --- a/docs/ibexa_cloud/install_on_ibexa_cloud.md +++ b/docs/ibexa_cloud/install_on_ibexa_cloud.md @@ -9,13 +9,14 @@ month_change: false ## 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 @@ For information about available services, see [Platform.sh documentation](https: 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 index d3cdebca6b..cf084b486d 100644 --- a/docs/infrastructure_and_maintenance/cache/persistence_cache.md +++ b/docs/infrastructure_and_maintenance/cache/persistence_cache.md @@ -156,7 +156,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 =]]/Platform.sh: This is automatically configured in `vendor/ibexa/core/src/bundle/Core/DependencyInjection/IbexaCoreExtension.php` if you have enabled Redis as `rediscache` Platform.sh service. + For [[= product_name_cloud =]]/Platform.sh, 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 index 0d4023d7f6..c3786cac7b 100644 --- a/docs/infrastructure_and_maintenance/clustering/clustering.md +++ b/docs/infrastructure_and_maintenance/clustering/clustering.md @@ -143,10 +143,9 @@ 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: ~ @@ -158,12 +157,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 index 1f4dec5288..b20e94c1c5 100644 --- a/docs/infrastructure_and_maintenance/sessions.md +++ b/docs/infrastructure_and_maintenance/sessions.md @@ -90,7 +90,7 @@ Alternatively if you have needs to configure Redis servers dynamically: !!! note "[[= product_name_cloud =]]" - For [[= product_name_cloud =]] (and Platform.sh), this is already configured in `config/env/platformsh.php` based on `.platform.yaml` config. + For [[= product_name_cloud =]] (and Platform.sh), 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 index 4affdc5f5d..a3c416c21c 100644 --- a/docs/release_notes/ibexa_dxp_v5.0.md +++ b/docs/release_notes/ibexa_dxp_v5.0.md @@ -10,6 +10,25 @@ month_change: true
+[[% set version = 'v5.0.5' %]] + +[[= 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 Platform.sh 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). + +[[% include 'snippets/release_50.md' %]] + +[[= release_note_entry_end() =]] + [[% set version = 'v5.0.4' %]] [[= release_note_entry_begin("Integrated help " + version, '2025-12-10', ['Headless', 'Experience', 'Commerce', 'LTS Update', 'New feature']) =]] diff --git a/docs/resources/new_in_doc.md b/docs/resources/new_in_doc.md index 245e147c18..d49c4c711c 100644 --- a/docs/resources/new_in_doc.md +++ b/docs/resources/new_in_doc.md @@ -7,6 +7,17 @@ month_change: true This page contains recent highlights and notable changes in [[= product_name =]] documentation. +## December 2025 + +### 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. + ## November 2025 ### 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 index 1e5e3876f1..2056be093f 100644 --- 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,14 +286,14 @@ The example is based on multi-core setup so any specific language analysis optio ibexa_solr: endpoints: main: - dsn: '%solr_dsn%' - core: '%solr_main_core%' + dsn: '%env(string:SOLR_DSN)%' + core: '%env(string:SOLR_MAIN_CORE)%' en: - dsn: '%solr_dsn%' - core: '%solr_en_core%' + dsn: '%env(string:SOLR_DSN)%' + core: '%env(string:SOLR_EN_CORE)%' fr: - dsn: '%solr_dsn%' - core: '%solr_fr_core%' + dsn: '%env(string:SOLR_DSN)%' + core: '%env(string:SOLR_FR_CORE)%' # ... connections: default: @@ -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 diff --git a/docs/update_and_migration/from_5.0/update_from_5.0.md b/docs/update_and_migration/from_5.0/update_from_5.0.md index 530bb64912..2a3ec1d968 100644 --- a/docs/update_and_migration/from_5.0/update_from_5.0.md +++ b/docs/update_and_migration/from_5.0/update_from_5.0.md @@ -154,6 +154,32 @@ Run the provided SQL upgrade script to add the missing indexes to your database: No additional steps needed. +## v5.0.5 + +### [[= product_name_cloud =]] configuration update + +If you're using [[= product_name_cloud =]], you must install a new package and update your cloud configuration. + +First, install the `ibexa/cloud` package: + +```bash +composer require ibexa/cloud +``` + +Then, update your cloud configuration. The old command `composer ibexa:setup --platformsh` has been replaced with: + +```bash +php bin/console ibexa:cloud:setup --upsun +``` + +This command generates or updates the cloud configuration files. + +Additionally, you must remove the following line from your `.platform.app.yaml` file if it exists: + +```yaml +curl -fs https://get.symfony.com/cloud/configurator | bash +``` + ## LTS Updates and additional packages [LTS Updates](editions.md#lts-updates) are standalone packages with their own update procedures. diff --git a/mkdocs.yml b/mkdocs.yml index b1a7052bea..000ce34459 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -812,6 +812,7 @@ nav: - Ibexa Cloud: ibexa_cloud/ibexa_cloud.md - Ibexa Cloud guide: ibexa_cloud/ibexa_cloud_guide.md - Install on Ibexa Cloud: ibexa_cloud/install_on_ibexa_cloud.md + - Environment variables: ibexa_cloud/environment_variables.md - DDEV and Ibexa Cloud: ibexa_cloud/ddev_and_ibexa_cloud.md - Infrastructure and maintenance: - Infrastructure and maintenance: infrastructure_and_maintenance/infrastructure_and_maintenance.md