Skip to main content
Version: 2023.2

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​

Before installing the Portal Engine, please be aware of the following requirements:

  • PHP >= 8.0
  • Pimcore >= 10.5
  • Elasticsearch 8
  • 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 to be configured and installed first:

Installation​

As soon as all prerequisites are met, installation follows standard composer and Pimcore procedure, depending on the version you're working with:

For Pimcore >= 10.5​

Follow the three steps below:

  1. Install the required dependencies:
composer require pimcore/portal-engine
  1. Make sure the bundle is enabled in the config/bundles.php file. The following lines should be added:
use Pimcore\Bundle\PortalEngineBundle\PimcorePortalEngineBundle;
// ...

return [
    // ...
    // make sure required bundles are added before to that list
    // ...
    PimcorePortalEngineBundle::class => ['all' => true],
    // ...
];
  1. Install the bundle:
bin/console pimcore:bundle:install PimcorePortalEngineBundle

For Older Versions​

Please run the following commands instead:

composer require pimcore/portal-engine
# if on Pimcore 10.5 enable bundle before installing
bin/console pimcore:bundle:enable PimcorePortalEngineBundle
bin/console pimcore:bundle:install PimcorePortalEngineBundle

Setup Elasticsearch​

Next step is to connect Elasticsearch to the Portal Engine. Elasticsearch client configuration takes place via Pimcore Elasticsearch Client Bundle and has two parts:

  1. Configuring an Elasticsearch client.
  2. Define the client to be used by Portal Engine.
# Configure an Elasticsearch client 
pimcore_elasticsearch_client:
    es_clients:
        default:
            hosts: ['elastic:9200']
            username: 'elastic'
            password: 'somethingsecret'
            logger_channel: 'pimcore.elasicsearch'    
            
# Define the client to be used by Portal Engine
pimcore_portal_engine:
    index_service:
        es_client_params: 
            es_client_name: default  # default is default value here, just need to be specified when other client should be used.

For further configuration options of the client (like authentication) have a look at Pimcore Elasticsearch Client Bundle.

By default, all data sources and trackers for statistics tracking based on Statistics Explorer also use the Elasticsearch client defined in pimcore_portal_engine section. To change that, please overwrite the service definitions for the corresponding trackers and datasources.

Define Index Prefix​

To avoid duplicate names or index interferences in Elasticsearch, it is necessary to define an index name prefix, which is added to all Elasticsearch indices created by Portal Engine. Default one is portalengine_.

This can be done by defining following parameter:

parameters: 
    pimcore_portal_engine.elasticsearch.index_prefix: 'portalengine_' # Prefix for all index names created by Portal Engine

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 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

Follow-up Configuration​

Portal Engine needs the following commands up and running permanently or regularly.

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, which all have meaningful default values:

  • 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 Messenger messaging queue.

Messaging Queue​

Set up the Symfony Messenger messaging queue like described in the Background Processes chapter.

(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.