Zesje is an online grading system for written exams.
Running Zesje using Docker is the easiest method to run Zesje yourself with minimal technical knowledge required. For this approach we assume that you already have Docker installed, cloned the Zesje repository and entered its directory.
First create a volume to store the data:
docker volume create zesje
Then build the Docker image using the following below. Anytime you update Zesje by pulling the repository you have to run this command again.
docker build -f auto.Dockerfile . -t zesje:auto
Finally, you can run the container to start Zesje using:
docker run -p 8881:80 --volume zesje:/app/data-dev -it zesje:auto
Zesje should be available at http://127.0.0.1:8881. If you get
the error 502 - Bad Gateway it means that Zesje is still starting.
Zesje currently doesn't support native Windows, but WSL works.
We recommend using the Conda tool for managing your development environment. If you already have Anaconda or Miniconda installed, you may skip this step.
Install Miniconda by following the instructions on this page:
https://conda.io/miniconda.html
Make sure you cloned this repository and enter its directory. Then create a Conda environment that will automatically install all of zesje's Python dependencies:
conda env create # Creates an environment from environment.yml
Then, activate the conda environment:
conda activate zesje-dev
You should see (zesje-dev) inserted into your shell prompt.
This tells you that the environment is activated.
Install all of the Javascript dependencies:
yarn install
Unfortunately there is also another dependency that must be installed manually for now (we are working to bring this dependency into the Conda ecosystem). You can install this dependency in the following way on different platforms:
| OS | Command |
|---|---|
| macOS | brew install libdmtx |
| Debian, Ubuntu | apt install libdmtx-dev |
| Arch | pacman -S libdmtx |
| Fedora | dnf install libdmtx |
| openSUSE | zypper install libdmtx0 |
If this is the first time that you will run Zesje with MySQL in development, then run the following command from the Zesje repository directory:
yarn dev:mysql-init
That's all it needs to create the MySQL files in the data directory, migrate the database to the last schema and move all your previous data.
Activate your zesje development environment and run
yarn dev
to start the development server, which you can access on http://127.0.0.1:8881.
It will automatically reload whenever you change any source files in client/
or zesje/.
By default, login is disabled during development but it can be enabled by setting LOGIN_DISABLED = False in
the development configuration file. You can see the set of supported login providers in
constants.py but take into account that for GitLab and Surf Conext you will need to request
for a valid CLIENT_ID and CLIENT_SECRET.
In case you only want to test the flow, you can set the provider to mock and start the
mock oauth server in a different terminal from where you
started the development server by running yarn dev:oauth.
The script example_data.py can be used to create a sample exam that mimics the appearance and behavior of a typical grading process in Zesje. The prototype exam consist on 3 open answer questions per page and 1 multiple choice question per page (excluding the first one). The script partially solves those questions and assigns random feedback to the answered questions while the not answered questions are processed as blank.
The script is called from the command line with the following parameters:
-d, --deleteIf specified, removes any existing data and creates a new empty database. Otherwise, new exams are added without deleting previous data.--exams (int)the number of exams to add, default is 1.--pages (int)the number of pages per exam, default is 3.--students (int)the number of students per exam, default is 30--graders (int)the number of graders to add, default is 4.--solve (float)between 0 and 100, indicates the percentage of questions to answer (including MCQ), default is 90%.--grade (float)between 0 and 100, indicate the percentage of solved questions to grade (that is, excluding blank answers), default is 60%.--skip-processingif specified, fakes the pdf processing to reduce time. As a drawback, blanks will not be detected.--multiple-copies (float)between 0 and 100, indicates how much of the students submit multiple copies, default is 5%
The actual processing of the exam takes a while, specially when the number of students is large.
You can run the tests by running
yarn test
As a test coverage tool for Python tests, pytest-cov is used.
To view test coverage, run
yarn test:py:cov
A coverage report is now generated in the terminal, as an XML file, and in HTML format. The HTML file shows an overview of untested code in red.
There is a plugin called Coverage Gutter that will highlight which lines of code are covered. Simply install Coverage Gutter, after which a watch button appears in the colored box at the bottom of your IDE. When you click watch, green and red lines appear next to the line numbers indicating if the code is covered.
Coverage Gutter uses the XML which is produced by yarn test:py:cov, called cov.xml. This file should be located in the main folder.
To view test coverage in PyCharm, run yarn test:py:cov to generate the coverage report XML file cov.xml if it is not present already.
Next, open up PyCharm and in the top bar go to Run -> Show Code Coverage Data (Ctrl + Alt + F6).
Press + and add the file cov.xml that is in the main project directory.
A code coverage report should now appear in the side bar on the right.
If you encounter PolicyErrors related to ImageMagick in any of the previous steps, please try the instructions listed here as a first resort.
Zesje uses Flask-Migrate and Alembic for database versioning and migration. Flask-Migrate is an extension that handles SQLAlchemy database migrations for Flask applications using Alembic.
To change something in the database schema, simply add this change to zesje/database.py. After that run the following command to prepare a new migration:
yarn dev:prepare-migration
This uses Flask-Migrate to make a new migration script in migrations/versions which needs to be reviewed and edited. Please suffix the name of this file with something distinctive and add a short description at the top of the file. To apply the database migration run:
yarn dev:mysql-migrate # (for the development database)
yarn migrate # (for the production database, MySQL must be running)
Adhere to PEP8, but use a column width of 120 characters (instead of 79).
If you followed the instructions above, the linter flake8 and the formatter black are installed in your virtual environment. If you use Visual Studio Code, install the Python extension and add the following lines to your workspace settings:
"python.linting.pylintEnabled": false,
"python.linting.flake8Enabled": true,
"[python]": {
"editor.rulers": [120],
"editor.defaultFormatter": "ms-python.black-formatter",
"editor.formatOnSave": true
},
"black-formatter.args": [
"--line-length=120"
]
If you use Atom, install the linter-flake8 plugin and add the following lines to your config:
".source.python":
"editor":
"preferredLineLength": 120
Adhere to StandardJS.
If you use Visual Studio Code, install the ESLint plugin.
If you use Atom, install the linter-eslint plugin.
If you start using a new Python library, be sure to add it to environment.yml.
The packages can be installed and updated in your environment by conda using
conda env update
Yarn keeps track of all the client-side dependancies in package.json when you install new packages with yarn add [packageName]. Yarn will install and update your packages if your run
yarn install
Zesje is licensed under AGPLv3, which can be found in LICENSE. An summary of this license with it's permissions, conditions and limitations can be found here.