Download the PHP package flarum/realtime without Composer

Realtime provides a self-hosted alternative to Pusher with far more features and an active development roadmap. It offers realtime updates of activity on your forum, not just for members but also for guests.

Features

• Auto update of index (while keeping permissions & subscription states in mind).
• Auto update of notifications (likes, replies, but also for flags).
• New posts pushed into discussions.
• Typing indicator showing the amount of people currently working on a reply in a discussion.

Requirements

Realtime contains a service you will need to install on your hosting environment, similar to the database service (MySQL) or web service (Apache, Nginx). As such you need your own virtual machine, droplet or an environment that allows you to configure scripts to run continuously. In addition, you will need to run a queue, we highly recommend the redis queue in combination with realtime.

For this reason this extension isn't likely applicable to anyone hosted on shared hosting environments.

Set up

Method a) use the defaults

No action needed. Your websocket will re-use the configuration of your existing forum.

Method b) the config.php

Create a key websocket and override any of the configuration items:

Configuration

All options:

• server-*, these options are used for the daemon itself, it specifies what ip/host and port to listen to.
  • server-host / default(0.0.0.0) ; on which host the realtime daemon listens
  • server-port / default(6001) ; on which port the realtime daemon listens
• js-client-*, these are used by the Flarum forum frontend (javascript) to connect to the Realtime websocket daemon.
  • js-client-host / default(config url) ; the host on which the Flarum forum will connect to the websocket server
  • js-client-port / default(6001) ; the port on which the Flarum forum will connect to the websocket server
  • js-client-secure / default(config url is https then yes, otherwise no) ; whether the Flarum forum will encrypt its connection to the websocket server
• php-client-*, when the Flarum backend wants to dispatch events to all users connected to Realtime it will push data to the Realtime daemon with these settings.
  • php-client-host / default(config url) ; the host to which the Flarum backend will send events
  • php-client-port / default(6001) ; the port to which the Flarum backend will send events
  • php-client-secure / default(config url is https then yes, otherwise no) ; whether the Flarum backend will communicate encrypted with the Realtime daemon
  • php-client-timeout / default(3) ; when the Flarum backend sends events to the Realtime daemon it will timeout in this number of seconds
• app-*, these define the authorization between server, javascript and daemon
  • app-key / default(hashed version of config url) ; the publicly available key to authenticate with against the Realtime daemon
  • app-secret / default(hashed version of database password) ; the secret password to grant access to private channels and to dispatch events to the Realtime daemon with
• max-connections / default(1000), the maximum number of allowed concurrent connections. Reduce this number to lower the strain on your server in case you notice the Realtime daemon being a problem.

Run the websocket server

For the websocket to run you will need to run its server. To do so for testing purposes, use:

This will boot the server and throw any debug information it can. This will keep the server running for as long as you keep this tab/window open.

The webservice will only run for as long as you keep your window open or your pc on using the above command. Using the realtime service in production requires setting it up as a daemon. See below for instructions for supervisor or systemd.

Daemon with supervisor

In production, you will need to set the websocket server to run continuously and restart when it errors. You can use a tool like supervisord for that.

Now create a new file inside the /etc/supervisor/conf.d directory called realtime.conf with:

• /var/www/flarum being the path to your Flarum installation, update this under the command line.
• www-data being the web user that runs your Flarum forum in apache, nginx or other web server software. Update under the user line.

Now read the configuration file and start the service:

Check whether the program is running:

More information about supervisor and its commands can be found in their documentation.

Daemon with systemd

Create a file with vim, vi or another editor of your choice at /etc/systemd/system/flarum-realtime.service with these contents:

Make sure to update the WorkingDirectory to match the directory where you installed Flarum. Update ExecStart to your version of php, you can use whereis php or whereis php80 to seek the path for each php version. Update the User to the user your site runs as.

Now reload the systemd service to pick up the service:

Start your service:

To understand whether it runs:

Now make sure to automatically start the service on reboots:

Auto restarting

The daemon will halt itself within 10 seconds when it identifies any change in your extensions. If you en- or disable an extension the daemon will stop. If properly set up this will allow the daemon to understand your Flarum changes and operate with the enabled extensions.

You can disable this feature by setting the --ignore-extension-toggles flag on the daemon:

Manually restarting

In case you want to force a restart within 10 seconds, for instance when using CI/CD, you can use the realtime:halt command:

Running encrypted

If you want to run the websocket server encrypted, the easiest way is to proxy the port with your webserver software (apache, nginx).

For nginx you can use the provided nginx configuration. Make sure to put the realtime nginx include before your flarum nginx include. Make sure to put both of these at the end of your server block:

We don't have examples for other webservers yet, but we'll gladly assist you with the installation on the Advanced edition.

Optional: to reduce overhead on your community from Flarum trying to interact with a remote url for sending realtime events, we can configure Flarum to use the current server as a target. To do so we can update our Flarum config.php like this:

FAQ

How many concurrent users does Realtime support? Resource usage of the websocket is really low. You should be able to serve thousands simultaneous users with only 1 cpu and 1 GB of memory dedicated to the process. Once we are able to provide a better indication from usage at scale, we will update this FAQ item. As a general rule of thumb it's always better to oversize your realtime daemon resource limitations and then - based on experience - reduce them to meet actual resource cost.

SendTriggerJob fails/is killed. In case the queue job SendTriggerJob fails every single time, make sure to increase the timeout of the queue worker. The default timeout is 60, also when you leave out the flag, so try running it with 360 like so: php flarum queue:work --timeout=360. Read the documentation of your queue driver to understand how to daemonize this command, for testing you can run it in your window with the additional -vvv flag for verbose logging.