Ansible Role: Mercure

Overview

This Ansible role helps you deploy Mercure on Linux systems with amd64 architecture using systemd.

Mercure is a protocol that allows you to send live updates to web browsers and other HTTP clients quickly and efficiently. It's ideal for sending asynchronous and real-time data updates from web APIs to responsive web and mobile applications.

For more information, you can visit the Mercure GitHub repository.

Requirements

• A Linux operating system with amd64 architecture.
• Systemd as the service manager.

Role Variables

Version

You can specify the version of Mercure to install using the mercure_rocks_release variable. For example:

mercure_rocks_release: "0.9.0"

If you don't set this variable, the latest version will be installed. If you run the playbook again after a new version is released, Mercure will update automatically.

Predefined Variables

• mercure_rocks_user: The system user and group, set to mercure.

• mercure_rocks_addr: The address and port Mercure will listen on, default is "127.0.0.1:3000".

• mercure_rocks_compress: Enables HTTP compression, set to "true" (or "false" to disable).

• mercure_rocks_cors_allowed_origins: Specifies allowed CORS origins, default is "*".

• mercure_rocks_debug: Enables debug mode, set to "false" (or "true").

• mercure_rocks_demo: Enables demo mode, set to "false" (or "true" when debug is enabled).

• mercure_rocks_log_format: Sets log format, options are JSON, FLUENTD, or TEXT (default).

• mercure_rocks_transport_url: URL for the history database, default "null://" disables history.

Security

Mercure uses JWT (JSON Web Tokens) for security. You have three options:

1. Use the same JWT secret key for both subscribers and publishers.
2. Use different keys for subscribers and publishers.
3. Use a key for publishers and allow anonymous access for subscribers.

You can create secret keys with online tools, such as this key generator.

Example Configurations:

1. Same key for subscribers and publishers:

   mercure_rocks_jwt_key: "your_secret_key"
   mercure_rocks_jwt_algorithm: "HS256"
   

2. Different keys for each:

   mercure_rocks_publisher_jwt_key: "publisher_key"
   mercure_rocks_subscriber_jwt_key: "subscriber_key"
   

3. Key for publishers with anonymous subscriber access:

   mercure_rocks_publisher_jwt_key: "publisher_key"
   mercure_rocks_allow_anonymous: "true"
   

For full options, check the Mercure documentation.

Dependencies

There are no dependencies for this role.

Example Playbook

Here is how to use the role in a playbook:

- hosts: servers
  vars_files:
    - vars/main.yml
  roles:
    - { role: teknipc.mercure }

In vars/main.yml, you could define:

mercure_rocks_jwt_key: "your_secret_key"
mercure_rocks_jwt_algorithm: "HS256"
mercure_rocks_release: "0.9.0"

License

This role is licensed under the BSD License.

Author Information

This role was created by Denis Soriano from TeKniPC.

Mercure Credits

• Lead Developer: Kevin Dunglas
• Mercure Website
• Mercure GitHub Repository
• Mercure is supported by Les-Tilleuls.coop