Running the Plom server

The server handles all communication between the database (which stores all the information about your test) and the various clients, including plom-client, plom-manager and plom-scan. There are 4 steps to getting the server runing.

Directories and Initialise

Decide on a working directory for the server. This need not be where you built the papers, but that is not a bad location. We recommend that you do not run the server on an NFS mounted drive. We are going to (for the purposes of this walk-through) create a directory called mABCserver and run the server there. Move into that directory and run plom-server init.

$ plom-server init
Do simple existence checks on required files.
Cannot find 'specAndDatabase' directory - you must copy this into place before running server. Cannot continue.

So Plom is telling us that it needs the specAndDatabase directory that was created when we built the PDFs. It is sufficient to copy that subdirectory into our current directory. Once that is done, rerun plom-server init:

$ plom-server init
Do simple existance checks on required files.
Directory 'specAndDatabase' is present.
Test specification present.
Database present.
Classlist present.
Build required directories
Building self-signed ssl keys for server
Generating a RSA private key
writing new private key to 'serverConfiguration/plom.key'
Copy server networking configuration template into place.
Please update 'serverConfiguration/serverDetails.toml' with the correct name (or IP) of your server and the port.
Build blank predictionlist for identifying.
Predictionlist already present.
Do latex checks and build 'pageNotSubmitted.pdf' in case needed
 Simple latex checks done.  If you feel the need, then please examine
'checkThing.png' and 'pns.0.0.0.png' in the directory 'pleaseCheck'.
The first should be a short latex'd fragment with some mathematics and
text, while the second should be a mostly blank page with 'page not
submitted' stamped across it.  It is safe delete both files and the

The command does some simple checks to make sure everything that we need is present: the specification, the database and the classlist. It also builds some new directories that the server will need, generates some SSL keys to encrypt communication with clients, runs some simple LaTeX checks. Most of this you can ignore (unless something breaks). You do, however, have to edit the serverDetails.toml file which you can find in the serverConfiguration subdirectory. Take a look

# >>> 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"

The Plom server doesn’t need too much information. 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.
  • The log-level will tune how much information is saved in plom’s logs. Leaving it set to "Info" for a test-run is reasonable, but you can probably set it to "Warning" or "Error" on a real test.


If you did not set up a classlist when you built PDFs, then you should run plom-server class. You can follow the same instructions as for plom-build class, but just use plom-server class instead.


One last task before we can launch the server — we need to 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 automagically. This latter option is particularly useful when you have a large marking team.

Manual user generation

Run plom-server users and Plom will construct a template for you to edit:

$ plom-server users
Creating 'serverConfiguration/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. Please do exercise some caution about what you do with this file and its contents. Do not, for example, email it to all your users. Open it up and edit it:

"manager", "123"
"scanner", "456"
"reviewer", "789"
"user0", "012"

Notice that the template contains the 3 special users, and one normal user. None of the supplied passwords are valid since they are too short. 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.

Automagical user generation

When you have a large marking team you probably don’t want to sit down and create all their usernames and passwords. To simplify this Plom can auto-generate random usernames and passwords for you. Then if you do have a large team you can simply 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 4
Creating an auto-generated user list at userListRaw.csv.
Please edit as you see fit and then rerun 'plom-server users serverConfiguration/userListRaw.csv'
Making list of named users

Now take a look at the resulting file:

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

The system has generated the 3 special users and 4 normal users. The passwords are generated using something like the xkcd scheme. 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 editted (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 serverConfiguration/userListRaw.csv
Processing user file 'serverConfiguration/userListRaw.csv' to 'userList.json'
Encoding password for user manager
Encoding password for user scanner
Encoding password for user reviewer
Encoding password for user duska
Encoding password for user talia
Encoding password for user usher
Encoding password for user yuri

The resulting list of users and hashed passwords will be stored in serverConfiguration/userList.json.

Launching the server

Now that we’ve done all the steps above, we can just run plom-server launch:

$ plom-server launch
Directory 'specAndDatabase' is present.
Test specification present.
Database present.
Classlist present.
Predictionlist present.


======== Running on ========
(Press CTRL+C to quit)

The server has found everything it needs and is up and running on the indicated IP and port.

While you can run the server this way, it is far better to run it with some protection from hangups. Consequently we recommend that you run the server with either nohup or screen — see nohup and screen respectively.

We are now ready to start processing scans and get on with marking.

Stopping the server

One can stop the server by simply killing the underlying python process.