Installation of Portal Engine
The installation of the portal engine follows standard composer procedures. There are a couple of things to consider though.
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)
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)
Furthermore, before the portal engine installation is possible, the following parameter has to be configured in the system:
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
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
Configure Symfony firewall
To configure the symfony firewall for the portals, add following line to your firewalls configuration
security.yml of your app after the
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
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.
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:
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.
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
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
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
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.