Mercure Setup

Start and Configure Mercure

It is recommended to use an up-to-date instance of Mercure, e.g. via their docker container. For details see Mercure docs.

Configuration

Configure JWT Key(s)

It is necessary to configure JWT keys for Mercure. These keys are used to sign and verify the JWT tokens that are used for authentication. You can choose to use the same key for both (use the jwt_key), or different keys for publisher (publisher_jwt_key) and subscriber (subscriber_jwt_key).

parameters:
    mercure:
        hub:
            jwt_key: 'YOUR_JWT_KEY_FOR_PUBLISHER_AND_SUBSCRIBER'
            #publisher_jwt_key: 'YOUR_JWT_KEY_FOR_PUBLISHER'
            #subscriber_jwt_key: 'YOUR_JWT_KEY_FOR_SUBSCRIBER'

Configure Mercure URLs (optional)

It is possible to configure URLs for accessing Mercure server-side (for updating state information within application services) and client-side (for getting updates in Pimcore admin interface) via symfony configuration tree as follows:

pimcore_direct_edit:
    mercure_settings:

        # URL of mercure accessible for client. If not set, default will be set to 'http(s)://<PIMCORE_HOST>/hub/.well-known/mercure'. Is is possible to use '<PIMCORE_SCHEMA_HOST>' as placeholder for current schema and host.
        client_side_url:      null

        # URL of mercure accessible for server. If not set, default will be set to 'http(s)://<PIMCORE_HOST>/hub/.well-known/mercure'.
        server_side_url:      null

You need to configure the full URL including protocol, port and path to Mercure here. For client side url it is also possible to use <PIMCORE_SCHEMA_HOST> for current schema and host of client. If these settings are not set, URLs will be generated based on Pimcore host and default paths.

Example Configuration with docker compose

Following there are configuration snippets for a setup with docker compose.

In that case, Mercure is only exposed via nginx reverse proxy that runs under https. Internal communication runs via http (which is handy when using self-signed certificates in development context).

docker-compose.yaml

Add mercure to your docker compose file and make sure to add the configuration for JWT keys.

  # add here all the other necessary containers... 

  # configure nginx to run under https
  nginx:
    image: nginx:stable-alpine
    ports:
      - 443:443
    depends_on:
      - php-fpm         
    volumes:
      - ./demo-px-enterprise:/var/www/html:ro
      
      # mount nginx configuration to be adapted (see below) 
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      
      # certificates for running nginx (for direct edit to work, system has to run with https)
      - ~/.certs:/etc/nginx/certs

  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      # Disable HTTPS
      SERVER_NAME: ':80'
      
      # Add JWT keys configured
      MERCURE_PUBLISHER_JWT_KEY: '<YOUR_JWT_KEY>'
      MERCURE_SUBSCRIBER_JWT_KEY: '<YOUR_JWT_KEY>'     
          

nginx.conf

Configure reverse proxy in nginx to route mercure traffic accordingly.

server {

    # (...) 
  
  	location /hub {
		proxy_pass http://mercure/.well-known/mercure;
	}

    # Thumbnails
    # (...)

}

config.yaml

Configure Pimcore application with JWT key as well as the client side and server side URLs for mercure.

parameters:
    mercure:
        hub:
            jwt_key: '<YOUR_JWT_KEY>'

pimcore_direct_edit:
    mercure_settings:
        # URL of mercure accessible for client.
        client_side_url:      <PIMCORE_SCHEMA_HOST>/hub
        # URL of mercure accessible for server.
        server_side_url:      http://mercure/.well-known/mercure

Check if Mercure is running

To see if Mercure is up and available, call https://your-app-domain.com/hub/.well-known/mercure (or client_side_url you configured in configuration). This request should return the text

Missing "topic" parameter.

Also execute curl https://your-app-domain.com/hub/.well-known/mercure (or server_side_url you configured in configuration) from the command line of the server to ensure that the URL is also accessible by the server itself.

Additional Aspects

Running Mercure with external URL

When running Mercure as external service with external URL, make sure to configure CSP properly.

Pimcore Configuration

pimcore_admin:
    admin_csp_header:
        additional_urls:
            connect-src:
                - 'https://<MERCURE_URL>/.well-known/mercure'

Mercure Configuration

Sample based on docker compose, important part is the cors_origins directive.

  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      # All other necessary configs ... 
      # ...
      
      # Add cors configuration
      MERCURE_EXTRA_DIRECTIVES: |-
          cors_origins "https://<YOUR_PIMCORE_URL>"

Webserver Reverse Proxy

When you are using Mercure default URLs, you might need to configure a reverse proxy to make sure the Mercure requests are routed correctly to the Mercure instance.

Also, keep in mind, that communication needs to be HTTPS. Thus, it might be useful to place the Mercure server behind a reverse proxy of the actual webserver (who handles the certificates).

Apache Reverse Proxy

For apache for example enable http_proxy in apache and add the following reverse proxy in your apache config:

   ProxyPass /hub/ http://mercure/.well-known/mercure
   ProxyPassReverse /hub/ http://mercure/.well-known/mercure

Nginx Reverse Proxy

For Nginx use following configuration:

	location /hub {
		proxy_pass http://mercure/.well-known/mercure;
	}

Legacy Fallback

The mercure binary is shipped because of BC reasons only. It is not recommended to use it, is not tested and thus might not work anymore. It also may contain security vulnerabilities.

As fallback, the bundle ships with an executable of Mercure. To run this Mercure executable, use following command:

./vendor/pimcore/direct-edit/bin/mercure --jwt-key=your-256-bit-secret-min-32-chars --addr=':3000' --debug --allow-anonymous --cors-allowed-origins='*' -f --debug

The hub must be permanently up and running. You can use following crontab example to ensure that:

*/5 * * * * /usr/bin/flock -n /tmp/mercure.lockfile /<system-path>/mercure --jwt-key=your-256-bit-secret --addr=':3000' --debug --allow-anonymous --cors-allowed-origins='*' -f