diff --git a/docs/administration/project_organization/bundles.md b/docs/administration/project_organization/bundles.md index 9f937b035c..d4d1d59e24 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 9af5247f6d..b434ccfdaf 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 "[[= 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 new file mode 100644 index 0000000000..5937a014bc --- /dev/null +++ b/docs/ibexa_cloud/environment_variables.md @@ -0,0 +1,123 @@ +--- +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. + +## 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` - Redis 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 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 0db9ef09ab..03bd6652cc 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 57e75ca9fc..69b622d2cb 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: true ## 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 [Upsun documentation](https://fixe 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 7772b83066..a58d58716d 100644 --- 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 index 4b7bbfa395..c6bcca8881 100644 --- a/docs/infrastructure_and_maintenance/clustering/clustering.md +++ b/docs/infrastructure_and_maintenance/clustering/clustering.md @@ -144,10 +144,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: ~ @@ -159,12 +158,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 6c5702a973..f91ad2b6b0 100644 --- 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 index 074b312180..6e2d8f138b 100644 --- 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
+[[% 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 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). + +### Full changelog + + + +[[= 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 index 0b52dbe7bc..ef270f8517 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. +## 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. + ## December 2025 ### Discounts 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 cc5f2031e0..afee4f8263 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,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 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 4e7a7a4d96..f6a2931bc2 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 @@ -281,6 +281,32 @@ Run the provided SQL upgrade script to ensure the Messenger tables for [backgrou psql < vendor/ibexa/installer/upgrade/db/postgresql/ibexa-5.0.4-to-5.0.5.sql ``` +## 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 77a37fda43..a9040f3ed7 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