Stackhero for Mercure-Hub

This add-on is operated by Stackhero

Mercure-Hub on dedicated instances, up-to-date versions and attractive prices.

Stackhero for Mercure-Hub

Last updated April 18, 2024

The Stackhero for Mercure-Hub add-on is currently in beta.

Stackhero for Mercure-Hub provides a managed Mercure-Hub service running on a fully dedicated instance.

The Stackhero for Mercure-Hub add-on provides the following features:

  • A private instance (dedicated VM) for high performances and security
  • TLS encryption (aka SSL)
  • An automatic backup every 24 hours
  • One click to update to new Mercure-Hub versions

Provisioning the add-on

Stackhero for Mercure-Hub can be attached to a Heroku application via the CLI:

For more information about available plans, see Stackhero for Mercure-Hub.

$ heroku addons:create ah-mercure-hub-stackhero --app <your app name>
-----> Adding ah-mercure-hub-stackhero to sharp-mountain-4005... done

After provisioning Stackhero for Mercure-Hub, the following config variables are available in your app’s configuration:

  • STACKHERO_MERCURE_HUB_HOST
  • STACKHERO_MERCURE_HUB_PUBLISHER_JWT_KEY
  • STACKHERO_MERCURE_HUB_SUBSCRIBER_JWT_KEY

You can see the content of these variables via the heroku config:get command:

$ heroku config:get STACKHERO_MERCURE_HUB_HOST
$ heroku config:get STACKHERO_MERCURE_HUB_PUBLISHER_JWT_KEY
$ heroku config:get STACKHERO_MERCURE_HUB_SUBSCRIBER_JWT_KEY

Local Setup

After you provision the add-on, you must replicate its config variables locally.

Use the Heroku Local command-line tool to configure, run, and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from an .env file. To view all of your app’s config variables, type heroku config. Use the following command for each value you want to add to your .env file:

heroku config:get <STACKHERO__VARIABLE> -s  >> .env

For example:

$ heroku config:get STACKHERO_MERCURE_HUB_HOST >> .env
$ heroku config:get STACKHERO_MERCURE_HUB_PUBLISHER_JWT_KEY >> .env
$ heroku config:get STACKHERO_MERCURE_HUB_SUBSCRIBER_JWT_KEY >> .env

Don’t commit credentials and other sensitive configuration values to source-control. In Git, exclude the .env file with: echo .env >> .gitignore.

For more information, see Heroku Local.

Connecting to the Stackhero Dashboard

View your instance usage, restart it, and apply updates with the Stackhero dashboard. You can access the dashboard via the CLI:

$ heroku addons:open ah-mercure-hub-stackhero
Opening ah-mercure-hub-stackhero for sharp-mountain-4005

You can also visit the Heroku Dashboard, select your application, and then select Stackhero for Mercure-Hub from the Add-ons menu.

Connecting Your Front-end to Mercure-Hub

The following example shows how to connect your front-end to Mercure-Hub:

const host = 'XXXXXX.stackhero-network.com';

const url = new URL('https://' + host + '/.well-known/mercure');

// Add topic to listen to
url.searchParams.append('topic', `https://${host}` + '/users/1234');
url.searchParams.append('topic', `https://${host}` + '/books/1');

const eventSource = new EventSource(url);

// The callback will be called every time an update is published
eventSource.onmessage = e => console.log(e);

Replace XXXXXX.stackhero-network.com per your instance host. You can identify the host with the following command:

$ heroku config:get STACKHERO_MERCURE_HUB_HOST

This example requires anonymous subscribers to work. You can enable anonymous subscribers in the Stackhero dashboard.

Connecting Your Back-end to Mercure-Hub

To connect your back-end to Mercure-Hub, use the following environment variables:

  • STACKHERO_MERCURE_HUB_HOST
  • STACKHERO_MERCURE_HUB_PUBLISHER_JWT_KEY

The following example shows how to connect to Mercure-Hub with Node.js:

const jwt = require('jsonwebtoken');
const request = require('request');
const process = require('process');

const host = process.env.STACKHERO_MERCURE_HUB_HOST;
const publisherJwtKey = process.env.STACKHERO_MERCURE_HUB_SUBSCRIBER_JWT_KEY;

// Defining the data we want to dispatch
const data = {
  // The topic where the data will be pushed
  topic: `https://${host}` + '/books/1',

  // The data that will send to the topic
  data: JSON.stringify({
    available: false,
    date: new Date()
  })
};


// Generating the bearer
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // Bearer expiring in one minute
    noTimestamp: true // Do not add "issued at" information to avoid error "Token used before issued"
  }
);


// Sending the data to Mercure-Hub that will dispatch them to clients
request.post(
  {
    url: `https://${host}/.well-known/mercure`,
    auth: { bearer },
    form: data
  },
  (err, res) => err ? console.error(err) : console.log(res)
);

Upgrading Your Plan

You can’t downgrade an existing add-on.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade ah-mercure-hub-stackhero:newplan
-----> Upgrading ah-mercure-hub-stackhero:newplan to sharp-mountain-4005... done
       Your plan has been updated to: ah-mercure-hub-stackhero:newplan

Manage migration timing to ensure your application is available during the migration process.

Removing the Add-on

You can remove Stackhero for Mercure-Hub via the CLI:

This destroys all associated data and can’t be undone!

$ heroku addons:destroy ah-mercure-hub-stackhero
-----> Removing ah-mercure-hub-stackhero from sharp-mountain-4005... done

Support

Stackhero for Mercure-Hub support and runtime issues should be submitted via one of the Heroku Support channels. We recommend adding support@stackhero.io in copy for urgent issues.

Additional Resources

Feedback

Log in to submit feedback.