catsoop help queue
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
adam j hartz 489b5aef2a
typo
5 months ago
README typo 5 months ago

README

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/).