Mercure is a hub or a protocol allowing services to push data or payload to other HTTP clients in a convenient, fast, reliable, and efficient way. LogBook can use Mercure to push alert messages from backend to frontend, enabling instant in-app notification which is more convenient than the periodic data polling method (sending periodic requests from frontend side). The latter is the default method LogBook will use when Mercure is not used.
Please note that using Mercure in LogBook is optional. Using a self-hosted Mercure as described in the following steps here is also optional, since Mercure provides a paid Managed Mercure Hub service as an alternative. You might want to use the paid service if you find the Mercure installation is difficult.
1. Installation
If you decide to self-hosting it, Mercure is available in various forms as you can see here including the prebuilt binary, Docker image, and so on. The following example shows you how to use Mercure in prebuilt binary with Supervisor or Systemd and install it in the same server as LogBook, making Mercure accessible from a different port (8080).
First you need to download the prebuilt binary archive from their release page. The following example uses Linux64 with the wget command:
wget https://github.com/dunglas/mercure/releases/download/v0.14.10/mercure_0.14.10_Linux_x86_64.tar.gz
Once download is finished, extract the archive by using tar command:
tar -xvf mercure_0.14.10_Linux_x86_64.tar.gz
then move the extracted binary to /usr/local/bin/ directory using the sudo command:
sudo mv mercure /usr/local/bin/
2. Create a Caddyfile
Create a config file for Mercure, for ex: /etc/caddy/Caddyfile:
{
{$GLOBAL_OPTIONS}
}
{$SERVER_NAME:localhost}
log {
format filter {
wrap console
fields {
uri query {
replace authorization REDACTED
}
}
}
}
{$EXTRA_DIRECTIVES}
route {
encode zstd gzip
mercure {
# Transport to use (default to Bolt)
transport_url {$MERCURE_TRANSPORT_URL:bolt://mercure.db}
# Publisher JWT key
publisher_jwt !ChangeThisMercureHubJWTSecretKey!
# Subscriber JWT key
subscriber_jwt !ChangeThisMercureHubJWTSecretKey!
# Permissive configuration for the development environment
cors_origins *
# Extra directives
{$MERCURE_EXTRA_DIRECTIVES}
}
header / Content-Type "text/html; charset=utf-8"
respond / `<!DOCTYPE html>
<html lang=en>
<meta charset="utf-8">
<meta name="robots" content="noindex">
<title>Welcome to Mercure</title>
<h1>Welcome to Mercure</h1>
<p>The URL of your hub is <code>/.well-known/mercure</code>.
Read the documentation on <a href="https://mercure.rocks">Mercure.rocks, real-time apps made easy</a>.`
respond /healthz 200
respond "Not Found" 404
}
- The provided configuration is a
Caddyfile used by the Caddy web server that is used by Mercure. The Caddyfile is a text-based configuration file that defines how Caddy should handle incoming HTTP requests.
publisher_jwt and subscriber_jwt specify the JWT keys for publishers and subscribers, respectively and don't forget to keep anonymous as you can see in the snippet above to allow subscribers without authentication to connect.- In the snippet above, you will have to change the value for publisher_jwt and subscriber_jwt (for ex.
!ChangeThisMercureHubJWTSecretKey!)
3. Background process setup
Notes
The following snippets use
8080 as the background process port, Please change it according to your needs.
If you are using Supervisor:
Create a new supervisor config for example in /etc/supervisor/conf.d/mercure.conf
[program:mercure]
environment=USE_FORWARDED_HEADERS=1, SERVER_NAME=:8080,
command=/usr/local/bin/mercure run --config /etc/caddy/Caddyfile
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/mercure.out.log
stderr_logfile=/var/log/mercure.err.log
This configuration instructs Supervisor to manage the execution, monitoring, and automatic restart of the mercure program. It sets environment variables, specifies the command to run, and configures logging options for both the standard output and standard error of the program.
Then run the following commands to start the process:
sudo supervisorctl reread && sudo supervisorctl update && sudo supervisorctl start mercure
If you use Systemd instead of Supervisor:
then create a new Systemd service for example in /etc/systemd/system/mercure.service
[Unit]
Description=Mercure Service
After=network.target
[Service]
Environment=USE_FORWARDED_HEADERS=1 SERVER_NAME=:8080
ExecStart=/usr/local/bin/mercure run --config /etc/caddy/Caddyfile
Restart=always
RestartSec=3
StandardOutput=file:/var/log/mercure.out.log
StandardError=file:/var/log/mercure.err.log
[Install]
WantedBy=multi-user.target
Run the following command anywhere to start the service:
sudo systemctl start mercure
To auto start the service on a system reboot, you can run:
sudo systemctl enable mercure
4. Proxy configuration
You can use NGINX or Apache for this purpose. Please note that they are using port 8080 as the default Mercure’s background process port as defined in Systemd or Supervisor config previously.
NGINX configuration:
location /.well-known/mercure {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
In this configuration, NGINX is set to act as a reverse proxy for requests to Mercure. When a request is made to /well-known/mercure, NGINX will pass the request to the backend server running on http://localhost:8080.
Apache configuration:
<Location /.well-known/mercure>
ProxyPass http://localhost:8080/.well-known/mercure
ProxyPassReverse http://localhost:8080/.well-known/mercure
</Location>
Make sure to restart the Nginx/Apache service afterwards.
5. Using Mercure in LogBook
In your LogBook app, set Mercure as an alert channel in config/service.yaml so that notifications will be sent through Mercure:
parameters:
alert_channel:
- 'mercure'
then connect the Mercure hub with LogBook by adding the following configuration to the .env file:
MERCURE_URL=https://logbook.com/.well-known/mercure
MERCURE_PUBLIC_URL=https://logbook.com/.well-known/mercure
MERCURE_JWT_SECRET="!ChangeThisMercureHubJWTSecretKey!"
Notes
The snippet above assumes
https://logbook.com as the domain name of your LogBook installation. Please change it accordingly.
MERCURE_URL=https://logbook.com/.well-known/mercure is the URL that is used to connect to the Mercure hub. The Mercure hub is responsible for handling real-time updates and event publishing in the LogBook application.MERCURE_PUBLIC_URL=https://logbook.com/.well-known/mercure is the URL that clients can use to connect to the Mercure hub for subscribing to real-time updates.MERCURE_JWT_SECRET="!ChangeThisMercureHubJWTSecretKey!" Change the value according to the value of publisher_jwt inside your /etc/caddy/Caddyfile. This sets the MERCURE_JWT_SECRET environment variable to the specified JWT secret key used for authenticating with the Mercure hub.
Then finally, you need to run the following command:
php bin/console cache:clear
