Readme

This program consitutes a REST backend for the quiz service. It handles various commands corresponding to creating, updating, and locking quizzes. There is no deletion option, for future comparability, but deletion can be usually handled manually by someone with access to the database.

Features

1. The quizzes are stored in the database with all relevant settings, which include

   • Name, date, and place of the quiz
   • The teams, including possibly chosen individual names
   • Reachable points for each round
   • Reached points for each round
   • The number of questions in the regular rounds. The number of questions is only necessary for proper updates of the settings, it does not have any further use.

2. Upon quiz creation, the server also creates two PDF files.

   1. The main file is the sheet for the actual answers provided by the groups. The document is optimised for two-sided printing, and empty pages are inserted, when the number of pages is not a multiple of four. Additionally, the answer sheets contain a QR code with a link to the individual point page of the team. There is also some room for a team name, which can be entered by the moderator.

   2. The secondary document is a file containing only the QR codes. This document is intended for cases where users may have missed the use of the quiz management application, or when there are good reasons for using only individual sheets, and not the ones generated by the application.

      In practice, this file is probably more useful in an ad-hoc scenario than anywhere else, but there have been cases, where having the QR codes ready would have been handy.

3. Quizzes can be locked. Locked quizzes still appear on the front page, but are no longer presented as editable quizzes. Attempts to circumvent this feature will fail, since every write operation on a quiz is checked for being able to write. Upon locking the corresponding PDF files are deleted to reduce the used space.

4. The program is neither parallel nor distributed. In practice, this should not be a problem, since it is unlikely that two moderators compete on input on the same quiz. Should this scenario occur, only the later operation for every regular operation, and the earlier one in case of the lock operation, will win, since both operations will be computed in the sequence of their arrival.

Requirements

1. To install the program, Haskell is required. You can install it via the Haskell Platform on your operating system. The bounds on the individual dependencies are rather lax, so in theory, the project should be easy to install at any given time.

2. To run the program, you will need some kind of server. There are no fixed requirements here, because you can run various servers, including localhost, and it all depends on your set-up.

3. To obtain the PDF sheets you should have pdflatex installed and in your environment variable. Additionally, there are some non-standard packages used along the way, but all of them should be available in a general basic LaTeX distribution. The program will work without pdflatex as well, but then no sheets and particularly no QR codes will be generated.

Set-up

1. Clone this repository.

2. Given that Haskell and Stack are installed, call stack install. This will install the program in the corresponding folder usually used by Stack.

3. Run the program with parameters.

   1. If you are running it locally for testing, the parameters could be -b 127.0.0.1 -p 9000 These do specify the host (-b part) and the port (-p) part.

   2. When running on a proper server, the address is likely 0.0.0.0, since you want it to run as a service. The most convenient way is to set it up as a service, which is rather simple on Linux based systems.

   3. If you run the program on an https connection, you need to supply encryption parameters:

      1. --ssl-address=0.0.0.0

      2. --ssl-port=<portNumber>

      3. --ssl-cert=<certificate>

      4. --no-ssl-chain-cert or --ssl-chain-cert depending on whether or not you have a chain certificate.

      5. --ssl-key=<privatekey>

   4. The above steps should be enough to run the program. In the https context you may have to perform some additional steps. To have the capability for secure connections, the Haskell dependency snap needs to be installed with the parameter -fopenssl. To do that run stack build --flag snap-server:openssl. This may require the additional library libssl-dev. It is probably already installed (but may not be), the Haskell bindings for this library can be obtained via stack install HsOpenSSL. Afterwards, you can run stack install again to get the version that can handle secure connections.

4. The config.txt should contain values for the parameters described below. There are sensible defaults, but these have only little flexibility.

   1. serverQuizzesFolder: This is the relative physical path to the folder that contains or shall contain all the quizzes. In local test setting this is usually quizzes, i.e. the part of the URL after the main server path. This folder is only used for addressing the path on the server, nothing is written in the folder.

   2. sheetsFolder: This is the folder in which the quiz sheets will be placed. The path can be absolute or relative.

   3. serverSheetsFolder: This is the folder which will be used in the link for the quiz sheets.

   4. serverPath: The path to the server, usually localhost or the actual path to the server.

   5. databaseHost: The host for the database provider.

   6. databaseName: The name of the database that is used.

   7. databaseUser: The user which will be used by the application to access the database.

   8. databasePassword: Self-explanatory.

   9. databasePort: Self-explanatory.

Technology

1. The program is written in Haskell entirely.

2. Sensitive REST requests (i.e. posts) are secured by HMAC. This means that you cannot arbitrarily manipulate the quizzes, because you need a session key, which is only delivered upon login. You can, however, resend a previous update to post an earlier state, if you manage a man in the middle scenario. Still, this might prove difficult, if the connection is encrypted.

3. The program has a PostgresQL backend using the persistent library.

4. JSON encoding and decoding is handled by aeson.

5. elm-bridge is used for generating code for the Elm frontend.

6. The PDF files are generated with HaTeX and a QR code extension for JuicyPixels.