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.mit.edu/) instance, but it can probably
be tweaked to run without one.

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



Installation Instructions
-------------------------

1. Install the following dependencies:
   * CAT-SOOP (https://catsoop.mit.edu/) (Make sure to create at least one
                                           course)

   * RethinkDB (https://rethinkdb.com/) (see https://rethinkdb.com/docs/install/debian/)
   * Node.js (use Debian's packaged version of `nodejs` and `npm`, not the most recent)
   * NGINX (https://www.nginx.com/) (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
(https://expressjs.com/) 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 (https://github.com/neumino/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](https://www.ractivejs.org/) 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 (https://mochajs.org/) test framework
with Chai (https://chaijs.com/) for assertions.

Building and running is configured using Gulp (https://gulpjs.com/).