Link

This site uses Just the Docs, a documentation theme for Jekyll.

Initialising the Plom server

The server handles all communication between the database (which stores all the information about your test) and the various programmes, including plom-client, plom-manager, plom-create, plom-scan, and plom-finish.

Directories and Initialise

Decide on a working directory for the server. This need not be where you want to build your paper (or even on the same computer) but for the purposes of this walkthrough we will use a common directory called “midterm” which we create using:

$ plom-server init midterm
Build required directories
...
You may want to update 'serverConfiguration/serverDetails.toml' with the correct name (or IP) and port of your server.
...

You may also see output about SSL keys, LaTeX checks and other things. Most of this you can ignore (unless something breaks). You may however, want to edit the serverDetails.toml:

# >>> Edit the data below <<
# the name or IP address of the server
server = "localhost"
# the port on which networking communication will happen
port = 41984
# In order of severity; less serious messages will not be logged
# Debug, Info, Warning, Error, Critical
LogLevel = "Info"

For the purposes of this walk-through, we are just going to assume that we’ll run everythying locally (which is a good use case for small tests).

  • The server should be set to your server name or IP address; we’ll leave it as server = "localhost".
  • The port can be left as is, but you may need to set it to a different value depending on any firewalls etc that may be running. Your markers will need to know the port in order to connect to the server.

Users (optional)

You can skip this step and configure most user accounts once the server is running using the plom-create users and plom-create user commands.

Before we can launch the server we can set up some users. We need at least 4 users:

  • “manager” — this should be the instructor in charge of running the test. They can oversee the entire scanning, uploading, marking and finishing of the test.
  • “scanner” — this is the user who will process and upload scans. They should not be used for other tasks.
  • “reviewer” — this is the user who will be assigned by “manager” to review any papers after they have been marked. They should not be used for regular marking.
  • at least one regular user, ie one that will do the most common tasks of marking and identifying.

Plom gives you two ways to build your user list — either manually from a template, or automatically. Its also possible to add more users later, once the server is running, using the plom-create or plom-manager tools.

Manual user generation

Change to your “midterm” directory and run plom-server users to construct a template for you to edit:

$ cd midterm
$ plom-server users
Creating 'userListRaw.csv' - please edit passwords for 'manager', 'scanner', 'reviewer', and then add one or more normal users and their passwords. Note that passwords must be at least 4 characters and usernames should be at least 4 alphanumeric characters.

The userListRaw.csv file is plain-text, so anyone who can read that file can view the passwords. Open it up and edit it:

"user","password"
"manager", "1234"
"scanner", "4567"
"reviewer", "7890"
"user0", "0123"
"user1", "0123"
"user2", "0123"

Notice that the template contains the 3 special users, and some normal users. Change the passwords and rename “user0” if you like. Save the result and we’ll explain what to do with that file in a moment.

Automatic user generation

When you have a large marking team you may not want to sit down and create all their usernames and passwords. Plom can auto-generate random usernames and passwords for you and you can then supply each member of your team with one of these random users as needed. To generate $N$ users, run plom-server users --auto N:

$ plom-server users --auto 3
Creating an auto-generated named user list at 'userListRaw.csv'
Please edit as you see fit and then rerun 'plom-server users userListRaw.csv'

The file contains something like:

"user","password"
"manager","week73already"
"scanner","position75head"
"reviewer","give32big"
"duska","she40than"
"talia","lion94bell"
"usher","win34city"
"yuri","rainy60brave"

You can also use --auto N --numbered to create numbered users. The passwords are generated using something like the xkcd scheme. Again, You are free to edit the resulting file as you see fit.

Processing the raw user list

Now that userListRaw.csv has been created and edited (by either method), it needs to be checked and the passwords hashed. To do this rerun plom-server users on the raw user list:

$ plom-server users userListRaw.csv
Processing user file 'userListRaw.csv' to serverConfiguration/userList.json

At this point you can keep the userListRaw.csv somewhere safe or destroy it as you see fit (the server doesn’t use it).

Next we will run our server.