Skip to main content
Built for simplicity and performance, Mercure is widely used in the Symfony ecosystem and beyond for reactive UIs, real-time notifications, and live data streaming.

​
Supported versions

You can select the major and minor version. Patch versions are applied periodically for bug fixes and the like. When you deploy your app, you always get the latest available patches.

​
JWT Token Secret

The service generates the JSON Web Token (JWT) token secret. It’s available in the password field of the Mercure relationship in the PLATFORM_RELATIONSHIPS environment variable.

​
Relationship reference

For each service defined via a relationship to your application, Upsun automatically generates corresponding environment variables within your application container, in the $<RELATIONSHIP-NAME>_<SERVICE-PROPERTY> format. Here is example information available through the service environment variables themselves, or through the PLATFORM_RELATIONSHIPS environment variable.
You can obtain the complete list of available service environment variables in your app container by running upsun ssh env.Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the service environment variables directly rather than hard coding any values.

​
Usage example

​
1. Configure the service

To define the service, use the mercure type: Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

​
2. Define the route

To access the service URL, add an entry to the .routes key as shown below, replacing <SERVICE_NAME> with the name of your service:

​
3. Define the relationship

Define the relationship to the app as shown below:
You can define SERVICE_NAME as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.The example above leverages default endpoint configuration for relationships. That is, it uses default endpoints behind the scenes, providing a relationship (the network address a service is accessible from) that is identical to the name of that service.Depending on your needs, instead of default endpoint configuration, you can use explicit endpoint configuration.With the above definition, the application container (APP_NAME) now has access to the service via the relationship SERVICE_NAME and its corresponding service environment variables.

​
Example configuration

​
Use in app

To use the configured service in your app, add a configuration file similar to the following to your project. This configuration defines a single application (myapp), whose source code exists in the <PROJECT_ROOT>/myapp directory.
myapp has access to the mercure service via a relationship whose name is identical to the service name (as per default endpoint configuration for relationships). From this, myapp can retrieve access credentials to the service through the relationship environment variables.
myapp/.environment
# Set environment variables for common Mercure credentials.
# For more information, please visit {{< vendor/urlraw "docs" >}}/development/variables.html#service-environment-variables.
export MERCURE_USER="${MERCURE_USERNAME}"
export MERCURE_HOST="${MERCURE_HOST}"
export MERCURE_QUERY="${$MERCURE_QUERY}"
The .environment shown above in the myapp directory is automatically sourced by Upsun into the runtime environment, so that the variable MERCURE_HOST can be used within the application to connect to the service. Note that DATABASE_URL and all Upsun service environment variables, such as MERCURE_HOST, are environment-dependent. Unlike the build produced for a given commit, they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment. A file very similar to this is generated automatically for your when using the upsun project:init command to migrate a codebase to Upsun.
Last modified on March 16, 2026