The CAT-SOOP Queue

The Queue is a web application that provides a better way for students in a laboratory setting to request help or assessment in an orderly fashion without interrupting the flow of their work. This queue is intended to be run alongside a CAT-SOOP (https://catsoop.org/) instance, but it can probably be tweaked to run without one.

You can follow the development of this application at: https://catsoop.org/git/catsoop/queue

Installation Instructions

1. Install the following dependencies:

   • CAT-SOOP (Make sure to create at least one course)

   • RethinkDB (see https://rethinkdb.com/docs/install/debian/)

   • Node.js, must be version 14 or earlier :\

   • NGINX (Or any other reverse proxy)

2. Clone this repository somewhere (we'll call that location $QUEUE in these instructions)

3. Check out the branch you want: $ git checkout <branch_name>

   where <branch_name> is one of the following:

   • physical allows entering free-form location information (intended for in-person office hours)
   • remote like physical, but also allows auto-generating a Jisti Meet link for remote help
   • remote_only all interactions forcibly auto-generate a Jitsi Meet link, entering other links is not allowed
   • remote_staff each staff member chooses a chat link, which is shown to the students once they are claimed

4. Edit $QUEUE/config/params.js and $QUEUE/config/www_params.js to fit your use case.

5. Configure the queue user

   1. The script in $QUEUE/make_queue_user.py will initialize the API token for a user. Replace COURSE_ID with the relevant string for your setup. The username __queue__user__ can be replaced with anything that won't be a valid username for anyone in your system.

      If your catsoop logs are encrypted, that script will need the CATSOOP_CONFIG and CATSOOP_PASSPHRASE environment variables are set in order to work properly.

   2. Run the script, save the token it prints out, and create the file $QUEUE/config/passwords.js with the following contents:

      module.exports = {
          catsoop: 'YOUR_QUEUE_USER_CATSOOP_API_TOKEN',
      };
      

   3. If your queue needs to be able to submit questions or otherwise interact with your course, make sure the queue user has the necessary permissions in the catsoop course. To be able to perform checkoffs, for example, the queue user needs the "impersonate" permission.

6. Configure NGINX

   Add the following snippet to your config (probably /etc/nginx/sites-avaliable/default.conf or /etc/nginx.conf, depending on your setup). Replace COURSE_NAME and PORT with the name of your CAT-SOOP course and the port from the previous step. Make sure to leave the trailing slashes!

   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/;
   }
   

7. In $QUEUE, run npm install to install all of the node dependencies.

8. Set up the CAT-SOOP plugin and queue pages

   Some of the queue's functionality is in the form of a CAT-SOOP plugin and a CAT-SOOP page (or multiple pages, if you have multiple rooms). The build system will generate these from your params.js file when you run npm start, and it will generate new ones each time your configuration changes. To use the new versions each time they generate, make the following symlinks:

   • symlink $QUEUE/dist/catsoop/plugin to $COURSE_ROOT/__PLUGINS__/queue (or whatever you'd like to name the plugin)

   • symlink $QUEUE/dist/catsoop/pages to $COURSE_ROOT/queue (or wherever you'd like your queue to be)

   • (remote_staff branch only) symlink $QUEUE/catsoop/chat_link anywhere in your catsoop course, and update the chat_link variable in your config/www_params.json to match

   You may prefer not to use these auto-generated files. In that case, you can build them manually by running npm run gulp build-catsoop. The files will be created in $QUEUE/dist/catsoop, and you can copy or move them to the locations listed above.

9. In $QUEUE, run npm start to start the queue (preferably, do this in a screen or tmux session to keep the session running after you hang up)

Common Issues

• The queue plugin on lab pages / checkoffs doesn't work as expected.

  Set the queue_enable and queue_room variables on catsoop pages where you want the queue sidebar to appear. queue_enable should be set to True on those pages, and queue_room should match the room from $QUEUE/config/params.js where you want the requests for that lab to go. If the room should change based on section, etc, you can set it in a cs_post_load handler instead of directly in the preload.py file.

• npm start quits after printing "Finished 'build'" without starting.

  Sometimes RethinkDB doesn't like to quit when asked to, so it needs to be manually SIGKILLed. I usually accomplish this by running ps to get a list of processes, and running kill -9 to stop them all simultaneously.

• CAT-SOOP errors with "csq_display_name not defined"

  The queue depends on a question's csq_display_name in order to show something meaningful to students and staff members. It also depends on csq_name to submit checkoffs, but CAT-SOOP can auto-generate that for you. I recommend setting both variables yourself in each question.

• npm start results in an Unhandled rejection ReqlOpFailedError thrown from the database.

  This occurs when the code tries to access the database connection immediately after the database process has been started. It only occurs on some machines and is a result of the Javascript code trying to access the database before it is ready for read operations. A stop-gap solution is to add the following code to the end of the server/rethinkdb.js file. If the error still occurs, increase 1000 (the number of milliseconds to delay for).

  const start = new Date().getTime();
  while (new Date().getTime() < start + 1000) {}
  

Hacking on the Queue

Here's a general layout of how the queue's modules are broken up and what you need to know to start tweaking things to fit your use case.

server has everything that runs on the server side of the application. The entry point is server/index.js, which starts an Express server and a socket.io (https://socket.io/) server to listen for client connections.

server/queue.js is where all the socket.io handlers get added. server/entry_types.js is where all the entry operations are specified. The db object that each of these import comes from server/rethinkdb.js, which is a tiny wrapper around the configuration for rethinkdbdash. server/authentication.js has all the auth flow that sets queue permissions.

The web frontend lives in www. The entry point is www/js/queue.js, which contains everything related to setting up hooks and handlers for queue data operations. www/js/view.js contains everything related to the display of the queue as a table view, claim view, and student views. It mainly works using the Ractive templating and component framework. The template HTML files all live in www/templates/. www/scss contains all the SCSS files that get built into flat CSS, and www/audio gets included without modification.

The client that the web frontend imports is in imports/client.js.

Tests live in test and use the Mocha test framework with Chai for assertions.

Building and running is configured using Gulp.