How to Set Up a Remote Help Queue

This post will talk through the process of setting up an instance of the remote version of the catsoop Help Queue, which has been used a lot at MIT for managing open lab hours in large classes. In particular, we'll talk about the two options that are most likely to be useful during the fall 2020 semester (specifically, the remote-only versions of the help queue).

Hopefully this guide will answer some questions. But, of course, if something seems not to work, or if you have other questions, please feel free to ask!

What is the Help Queue

The help queue provides a way for students to ask for help in a lab-hours setting. Students click a button indicating that they want help, and staff see a list of everyone who is waiting for help, as well as information about the requests (how long have they been waiting, what do they need help with, etc). Staff can then "claim" help requests.

Even in in-person lab settings, this has proven really useful for managing large lab sessions where lots of students may be asking for help and many staff may be helping them; and even more so for remote-only lab hours.

In the remote version of the queue, student and staff are connected via video chat when a request is "claimed."

Remote Queue Variants

There are two versions of the help queue currently available: the regular "remote" queue, and a "flexible" remote queue. I'll refer to these as "regular mode" and "flexible mode" below.

In regular mode, the queue will automatically generate a Jitsi Meet video chat link for each queue entry, and student and staff can both navigate to that link to chat with each other.

In flexible mode, the queue allows for alternative chat backends. In this setup, each staff member sets up a permanent chat link (using an arbitrary tool of their choice) and enters this URL into a special catsoop page; later, when they claim a student request, the student is shown whatever link the staff member had entered.

There are benefits and drawbacks to each of these approaches; feel free to use whichever best fits your use case. The following instructions describe the setup process for both variants.


The queue depends on catsoop, Node.js, and RethinkDB. You can follow the instructions for installing Node.js and RethinkDB on their respective web sites. Note that the queue has been tested with Node.js version 12 (the current LTS release), but not with other versions.

The process described here (a fairly standard installation) also uses NGINX, though other reverse proxies should work just fine as well in you prefer them.

Downloading the Queue

The easiest way to get the code for the queue is to clone the Mercurial repository (or the Git mirror):

$ hg clone


$ git clone git://

Once you have downloaded the source code, you should update to the appropriate branch for your use case:

$ hg update remote  # for regular mode
$ hg update remote_flex  # for flexible mode

or, if using the Git mirror:

$ git checkout branches/remote
$ git checkout branches/remote_flex

Alternatively, if you prefer not to use Mercurial or Git, you can download a tarball containing the queue's source code:

Configuring the Queue

Setting Up A catsoop User

The queue uses catsoop's API to authenticate users and determine things like permissions. In order to do this, the queue needs an API token; so we start by creating a catsoop user and API token for the queue to use.

This should just involve running the script that is included in the queue distribution (but feel free to change pieces of it if need be). This script will create a new user and print an API token to the screen, and you should copy that token to your clipboard (or otherwise make a note of it).

Next, make a file config/passwords.js within the queue's source tree, and put the following content in it:

module.exports = {
    catsoop: "YOUR_API_TOKEN_HERE",

If your queue needs to be able to submit questions on behalf of students (for example, if you are using catsoop's built-in checkoff question type), you should make sure that the user you just created has the "submit_all" and "impersonate" permissions within your course.

Setting Staff Permissions

The queue uses catsoop roles to determine which actions each user should be able to take. By default, users with the "LA", "TA", "Instructor", or "Admin" roles can act as staff in the queue (i.e., can claim entries, give checkoffs, etc.). Everyone else has student access and so can make requests for help.

Make sure that all staff have an appropriate role set in their __USERS__ file.

Other Configuration in params.js

Edit the config/params.js file and adjust the following:

  • On line 27, edit the URL to reflect the root of your catsoop installation (no trailing slash).
  • On line 44, feel free to edit the URL there if you want the root of the queue to exist somewhere other than the usual location (this is arbitrary, but it will need to match the value from the NGINX configuration further down this page).
  • On line 49, set the rooms that you want to have. Each room gets its own queue. This was mainly used for in-person office hours spread across multiple physical rooms, but it can stil be useful if you want to split your remote queue into multiple logical units (maybe one for each section of a class, or something). But for most cases, it is probably fine to have a single room; I usually use ['default'] for this setting.

Feel free to change other things here as well.

Other Configuration in www_params.js

Edit the config/www_params.js file as well. The details will depend on whether you are using the regular or flexible remote queue, but there are some things that should be changed either way.

  • In either mode, set contact_email to be an e-mail address students should e-mail in case of issues.
  • In either mode, set get_photo_url to null.
  • In regular mode, if you want to use a self-hosted Jitsi Meet instance, set jitsi_meet_prefix to point to that instance.
  • In flexible mode, copy the catsoop/chat_link page from the queue's source tree into your catsoop course, and update chat_link in www_params.js to point to that page's location.

Other Customizations

The hope is that things mostly work out-of-the box. But it is certainly possible to make other changes to the queue. For most surface-level things, editing the files in www/templates are enough. But see the README file for more information about the codebase (or feel free to ask questions here!).

Configure NGINX

Add something like the following to your NGINX configuration:

    location /queue/COURSE_NAME/ {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
        proxy_pass http://localhost:PORT/;

Replace /queue/COURSE_NAME with the URL_ROOT you set in config/params.js and PORT with the port you set in config/params.js.

Don't forget to restart NGINX to make the queue available.

Installing and Starting the Queue

Finally, we can start and install the queue.

From the root of the queue's source tree, run npm install to set things up. This step may take a while, but when it is done, run npm start to start the queue. After a short warm-up period, the queue should be available via the web!

Is it possible to see a screenshot of the queue / its features? So I may decide if I want to put in the time to try it out. Thanks!