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

Following Mercure configuration aspects need to be considered

• Add same JWT key to MERCURE_PUBLISHER_JWT_KEY and MERCURE_SUBSCRIBER_JWT_KEY
• Activate anonymous to allow Pimcore Admin UI to connect to Mercure

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 here all the other necessary containers... 

  # configure ngnix to run under https
  nginx:
    image: nginx:stable-alpine
    ports:
      - 443:443
    depends_on:
      - php-fpm         
    volumes:
      - ./demo-px-enterprise:/var/www/html:ro
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ~/.certs:/etc/nginx/certs

  mercure.local:
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      # Disable HTTPS
      SERVER_NAME: ':80'
      MERCURE_PUBLISHER_JWT_KEY: '<YOUR_JWT_KEY>'
      MERCURE_SUBSCRIBER_JWT_KEY: '<YOUR_JWT_KEY>'     
      
      MERCURE_EXTRA_DIRECTIVES: anonymous      

nginx.conf

server {

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

    # Thumbnails
    # (...)

}

config.yaml

pimcore_direct_edit:
    mercure_settings:
        # URL of mercure accessible for client.
        client_side_url:      <PIMCORE_SCHEMA_HOST>/hub/mercure
        # URL of mercure accessible for server.
        server_side_url:      http://mercure.local/.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.

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://localhost:3000/
   ProxyPassReverse /hub/ http://localhost:3000/

Nginx Reverse Proxy

For Nginx use following configuration:

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

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