Warning: You are browsing the documentation from version 4 to 10 of Pimcore. Please visit https://pimcore.com/docs/platform/ for the latest versions of Pimcore.

Version:

Installation of Portal Engine

The installation of the portal engine follows standard composer procedures. There are a couple of things to consider though.

Prerequisites

System Requirements

Following requirements additionally to Pimcore apply:

PHP >= 7.4
Pimcore >= 6.9
Elasticsearch 6 or Elasticsearch 7
Mercure (optional for Pimcore Direct Edit)
MySQL/MariaDB innodb_default_row_format option needs to be set to "DYNAMIC" (which is the default value)

Required Bundles

The portal engine requires a couple of bundles which need be configured and installed first:

Enterprise Metadata Bundle
Statistics Explorer
Direct Edit (optional)
OpenId Connect (optional, if you like to use SSO via OpenID Connect)

Required Parameter

Furthermore, before the portal engine installation is possible, the following parameter has to be configured in the system (in parameters: configuration):

pimcore_portal_engine.elasticsearch.host: Host of your Elasticsearch cluster
pimcore_portal_engine.elasticsearch.index_prefix: Prefix for all index names created by portal engine

Installation

As soon as all prerequisites are met, installation follows standard composer and Pimcore procedure.

composer require pimcore/portal-engine
./bin/console pimcore:bundle:enable PimcorePortalEngineBundle
./bin/console pimcore:bundle:install PimcorePortalEngineBundle

If Elasticsearch access needs additional connection parameters (like e.g. authentication information), they can be configured as described below. Please be aware, a working ES connection is necessary during install (/bin/console pimcore:bundle:install PimcorePortalEngineBundle), thus defining additional parameters needs to be done after enable but before install.

Configure Symfony firewall

To configure the symfony firewall for the portals, add following line to your firewalls configuration in the security.yml of your app after the pimcore_admin firewall.

security:
    firewalls:
        pimcore_admin: 
            # ...
        portal_engine: '%pimcore_portal_engine.firewall_settings%'

Of course, it is also possible to customize the firewall settings for the portals by defining your custom settings instead of using the provided parameter. But, this is not recommended and might break in future versions of the portal engine (because the portal engine does changes at the firewall configuration)!

IMPORTANT If you need to exclude certain routes from the firewall and make them accessible without portal engine login (like for example for the open id connect integration for Pimcore backend), you can specify these routes in following configuration.
 pimcore_portal_engine:
   custom_public_routes:
   - pimcore_openidconnect_buttoninjection_script

Commands after Installation

It is recommended to run following commands after installation (at least) once:

./bin/console portal-engine:update:index-recreate
./bin/console portal-engine:update:process-index-queue --processes=5

Followup Configuration

For running the portal engine need following commands up and running permanently or on regular basis.

Index Updating Queue Cronjob

It is necessary to update the elastic search index on a regular basis. This can be done either via a command or via the symfony messaging queue.

Command Based

For command based queue processing, add the following cronjob to your crontab.

# it is ok to run it once a minute as it will be locked by a Symfony lock
* * * * * php /path/to/your/app/bin/console portal-engine:update:process-index-queue

# if needed it is possible to execute this with multiple parallel processes too
* * * * * php /path/to/your/app/bin/console portal-engine:update:process-index-queue --processes=4

Symfony Messenger Based

For symfony messenger based queue processing, at least following configuration needs to be done in symfony configuration:

pimcore_portal_engine:
    messenger_queue_processing:
        activated: true

If activated, the processing is kicked off automatically with the portal_engine.index_update_queue_dispatching maintenance task.

In addition to that, following settings are available. They all have meaningful default values though:

worker_count: Count of maximum parallel worker messages for queue processing
worker_item_count: Count of items processed per worker message.
worker_count_lifetime: Lifetime of tmp store entry for current worker count entry. After lifetime, the value will be cleared.

See also next point for setting up the symfony messaging queue.

Messaging Queue

Setup the Symfony messenger messaging queue like described in the Background Processes chapter.

(optional) Configuring ES client params (like basic auth)

For ES communication the official ES PHP client library is used. The portal engines EsClientFactory uses the ClientBuilder to build a client and configure it. Host and logger are configured automatically. In addition to that, it passes a connection_params array that can be set in pimcore_portal_engine configuration tree and allows configuring additional connection settings for the client (example see below).

Thus, it is for example possible to configure for example basic authentication, api key, additional headers and more. For details see ClientBuilder docs and implementation.

By default, all data sources and trackers for statistics tracking based on Statistics Explorer also use ES host and ES connection params defined in pimcore_portal_engine section. To change that, please overwrite the `` service definition and provide your custom values to $esHosts and $esConnectionParams.

Setup Basic Auth

To setup basic auth for elasticsearch client, use following configuration.

pimcore_portal_engine:
    index_service:
        es_client_params:
            connection_params:
                client:
                    curl:
                        !php/const CURLOPT_HTTPAUTH: !php/const CURLAUTH_BASIC
                        !php/const CURLOPT_USERPWD: 'my_user:my_password'

(optional) Multi-Node setup

When setting up the portal engine in a multi node setup, please first follow Pimcore instructions for multi-node setup and shared storages.

In addition to the Pimcore instructions also consider /var/tmp/portal-engine/downloads which needs to be a shared tmp folder and can be configured via flysystem configuration:

flysystem:
    storages:
        pimcore.portalEngine.download.storage:
            adapter: 'local'
            visibility: private
            options:
                directory: '%kernel.project_dir%/var/tmp/portal-engine/downloads'

Style Settings Feature

If you are using the style settings feature the location public/var/portal-engine needs to be shared along the nodes.

It contains some configuration files for webpack setup and customized frontend builds for portals that are using the style settings feature.