diff --git a/docs/dam/integration_with_dxp.md b/docs/dam/integration_with_dxp.md new file mode 100644 index 0000000000..e34df8dd2c --- /dev/null +++ b/docs/dam/integration_with_dxp.md @@ -0,0 +1,221 @@ +--- +description: Integrate DAM with your Ibexa DXP project to use an effective tool for managing marketing assets. +--- + + +# Integrate DAM with DXP + +DAM integration with [[= product_name =]] is dedicated to [[= product_name_base =]] users who want to use [[= product_name_base =]] as a data storage. It enables using assets repository stored in the DXP and manage assets. + +## Enable Elasticsearch or Solr + +To ensure proper indexing and search results, DAM requires one of +the following search engines on your server: + +- [Elasticsearch](install_elastic_search.md) +- [Solr](install_solr.md) + + +## Enable OAuth Server + +Next, enable OAuth Server authentication. To do it, follow steps up to the [Client section](oauth_server.md). + +## Integration with Platform.sh + +If you have your [[= product_name =]] project deplyed on Platform.sh, the following steps are required: + +In the `.platform.app.yaml` file, set paths for private and public keys to OAuth Server. +Next, generate these keys and add them. + +```bash +variables: + env: + # OAuth2 Server paths to certificates + OAUTH2_PRIVATE_KEY_PATH: /app/oauth-server.key + OAUTH2_PUBLIC_KEY_PATH: /app/oauth-server.pub + + +hooks: + build: | + # Generate OAuth2 Keys + openssl genrsa -out private.key 2048 + openssl rsa -in private.key -pubout -out public.key + + # OAuth2 Server credentials + export OAUTH2_PRIVATE_KEY="$(cat private.key | base64)" + export OAUTH2_PUBLIC_KEY="$(cat public.key | base64)" + + echo "$OAUTH2_PRIVATE_KEY" | base64 -d > ~/oauth-server.key + echo "$OAUTH2_PUBLIC_KEY" | base64 -d > ~/oauth-server.pub +``` + +## Install DAM package + +Install dedicated DAM `ibexa/dam-user` package into your [[= product_name =]] instance. + +To install, run the following command: + +```bash +composer require ibexa/dam-user +``` + +Add the `ibexa_dam_oauth2_client_user` table to the database: + +```bash +php bin/console ibexa:doctrine:schema:dump-sql vendor/ibexa/dam-user/src/bundle/Resources/config/schema.yaml | mysql -u -p +``` + +Next, create technical users, required by DAM to your [[= product_name =]] instance: + +- `image-picker-reader` - with read permission +- `imgage-picker-editor` - with edit/ delete permission + +Both users have limited access to Media folder only. + +To do it, first, import the migration file: + +```bash +php bin/console ibexa:migrations:import vendor/ibexa/dam-user/src/bundle/Resources/migrations/2024_07_11_09_10_dam_technical_users.yaml +``` + +Next, run migrations: + +```bash +php bin/console ibexa:migrations:migrate +``` + +Two new user roles and users should be now visibile in the Back Office. + +Create OAuth2 client for the DXP user: + +```bash +php bin/console ibexa:dam:create-oauth2-client +``` + +For example: + +```bash +php bin/console ibexa:dam:create-oauth2-client +``` + +## Override admin-ui + +Override parameters for `admin_group` and use `site_group` scope to make them available under REST API. + +Add the following configuration in the `yaml` file, for example, `ibexa_admin_ui_settings.yaml`: + +??? note "`ibexa_admin_ui_settings.yaml`" + + ```yaml + parameters: + # Content Tree Module + ibexa.site_access.config.site_group.content_tree_module.load_more_limit: 30 + ibexa.site_access.config.site_group.content_tree_module.children_load_max_limit: 200 + ibexa.site_access.config.site_group.content_tree_module.tree_max_depth: 10 + ibexa.site_access.config.site_group.content_tree_module.allowed_content_types: [] + ibexa.site_access.config.site_group.content_tree_module.ignored_content_types: [] + ibexa.site_access.config.site_group.content_tree_module.tree_root_location_id: ~ + + # Pagination limits + ibexa.site_access.config.site_group.pagination.search_limit: 10 + ibexa.site_access.config.site_group.pagination.trash_limit: 10 + ibexa.site_access.config.site_group.pagination.section_limit: 10 + ibexa.site_access.config.site_group.pagination.language_limit: 10 + ibexa.site_access.config.site_group.pagination.role_limit: 10 + ibexa.site_access.config.site_group.pagination.content_type_group_limit: 10 + ibexa.site_access.config.site_group.pagination.content_type_limit: 10 + ibexa.site_access.config.site_group.pagination.role_assignment_limit: 10 + ibexa.site_access.config.site_group.pagination.policy_limit: 10 + ibexa.site_access.config.site_group.pagination.version_draft_limit: 5 + ibexa.site_access.config.site_group.pagination.reverse_relation_limit: 10 + ibexa.site_access.config.site_group.pagination.content_system_url_limit: 5 + ibexa.site_access.config.site_group.pagination.content_custom_url_limit: 5 + ibexa.site_access.config.site_group.pagination.content_role_limit: 5 + ibexa.site_access.config.site_group.pagination.content_policy_limit: 5 + ibexa.site_access.config.site_group.pagination.bookmark_limit: 10 + ibexa.site_access.config.site_group.pagination.notification_limit: 5 + ibexa.site_access.config.site_group.pagination.user_settings_limit: 10 + ibexa.site_access.config.site_group.pagination.content_draft_limit: 10 + ibexa.site_access.config.site_group.pagination.location_limit: 10 + ibexa.site_access.config.site_group.pagination.url_wildcards: 10 + + # Security + ibexa.site_access.config.site_group.security.token_interval_spec: PT1H + + # User identifier + ibexa.site_access.config.site_group.user_content_type_identifier: ['user'] + + # User Group identifier + ibexa.site_access.config.site_group.user_group_content_type_identifier: ['user_group'] + + # Subtree Operations + ibexa.site_access.config.site_group.subtree_operations.copy_subtree.limit: 100 + + # Notifications + ibexa.site_access.config.site_group.notifications.error.timeout: 0 + ibexa.site_access.config.site_group.notifications.warning.timeout: 0 + ibexa.site_access.config.site_group.notifications.success.timeout: 5000 + ibexa.site_access.config.site_group.notifications.info.timeout: 0 + ``` + +## Add CROSS-ORIGIN config + +To integrate DAM you need to add in the `config/packages/nelmio_cors.yaml` following configuration: + +```yaml +nelmio_cors: + defaults: + origin_regex: true + allow_origin: ['%env(CORS_ALLOW_ORIGIN)%'] + allow_methods: ['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE', 'PUBLISH', 'COPY'] + allow_headers: ['Content-Type', 'Authorization', 'X-HTTP-Method-Override'] + expose_headers: ['Link'] + max_age: 3600 + paths: + '^/api/ibexa/v2/': + allow_methods: ['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE', 'PUBLISH', 'COPY'] + allow_headers: ['Content-Type', 'Authorization', 'X-HTTP-Method-Override'] +``` + +Next, in the `.env` file provide path with a regular expression and change the domain accroding to your needs: + +`CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1|(.+\.acme\.(com|eu)))?(:[0-9]+)?$'` + + +### Override `nelmio` settings + +config/services.yaml + +```yaml +nelmio_cors.options_provider.config: + class: '%nelmio_cors.options_provider.config.class%' + arguments: + $paths: '%nelmio_cors.map%' + $defaults: '%nelmio_cors.defaults%' + tags: + - + name: nelmio_cors.options_provider + priority: 255 +``` + +Set the `location ID` to `51`. +```yaml +parameters: + ibexa.dam_app.image.root_location_id: 51 +``` + +Add DAM `ConfigProvider`: + +```yaml +app.config.provider.dam_app: + class: Ibexa\AdminUi\UI\Config\Provider\Value + arguments: + $value: + imageRootLocationId: '%ibexa.dam_app.image.root_location_id%' + tags: + - { name: ibexa.admin_ui.config.provider, key: 'damApp' } +``` + +!!! caution + + Location ID must be set to 51, if you provide different location ID, your asset library won't be accessible from DAM. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 800afe512a..33a76c4cc3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -451,6 +451,8 @@ nav: - CDP add client-side tracking: cdp/cdp_activation/cdp_add_clientside_tracking.md - CDP data export schedule: cdp/cdp_data_export_schedule.md - CDP data customization: cdp/cdp_data_customization.md + - DAM: + - Integration with DXP: dam/integration_with_dxp.md - Search: - Search: search/search.md - Search engines: