These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

To develop on this project on your local machine (i.e your computer) you need to install

• Python 3.7
• pre-commit
• Docker
• GNU Make (This is pre-installed on Unix based systems)
• Git (This is pre-installed on Linux or Mac) Then follow this guideline to use it.

We use docker to develop on containers locally, a container is a more simple virtual machine of ubuntu. This is why we need to install docker on our system first, make sure on the terminal. Check if you have docker and docker-compose by doing:

$ docker -v
$ docker-compose -v

Here it is a makefile that does almost everything for you. To use it on your local machine (With a running Unix base system like linux with ubuntu distro) just type:

make <name_of_the_command>

The most important ones are described on the following table:

For all commands descriptions type make on the command line for help

On the container terminal there are some useful commands to use, which are used with:

easyexam <name-of-the-command>

This are resumend in:

First of all, this guide is for unix like system like linux with ubuntu. Then search (or make) the folder of this project and run the commands as told on this tutorial.

First of all download the repo on the local machine with https (or ssh if you have a ssh key configurated on your github)

$ git clone https://github.com/Ing2-Team2EasyExam/EasyExam.git

Fill the credentials with your own ones. Then install pre commit on this repo:

$ pre-commit install

This make when you commit, change the files to have a good structure. If a check doesn't pass, pre-commit will change the files so add them and make the commit again.

Now, we have our makefile that does everything for us. (Be sure that you have docker on your machine!). So first things first, let's build the container on your local machine:

$ make docker-build

This will take several minutes but when it's finished, do:

$ make docker-up

Now you will be on the docker container command prompt, so with this you can run the project. First things first, never use a git command here, this is only for running the project (making the migrations, etc...), nothing more than that.

So now let's start doing some migrations, for that run:

easyexam makemigrations
easyexam migrate

This commands will run the migrations to the postgresql, we have postgresql on the container (docker magic uau), so this is best when trying to have an environment close as posible to production.

Next up, let's set up the frontend. To do this, we run on the docker container:

$ easyexam install

That will install all the dependencies of the project, including our frontend and webpack.

After that let's add some initial data to our database, run:

$ easyexam fixtures

And that should load the initial users and data of our system.

Finally, let's run the server. Run on your terminal with docker:

$ easyexam runserver

So this have a lot of Unix based commands in order to run, so that is bad for Windows users. There are three approches, one easier to set up (but limited to your windows version), other one that is also easy to set up and is available to all windows version and one more difficult to set up and not limited to your windows version. The easier is more fast but I strongly recommend the more difficult one, because it will give you limited tools to use on future projects.

Because the first method is limited to only certain version of windows (Pro and educational), I will explain the two others.

Resume All this method is a combination of this video to install GNU Make, and this video to install docker. You must install Git command prompt first :)

So this first method will be installing Windows tools to make docker work and works for all versions of Windows (Home, Educational or Pro). This is faster to set up, but have very limitations (It doesn't give you a Linux kernel for example).

First, check if you have virtualization enabled. Open the task manager and see if virtualization is enabled (or on).

If you can't see it there, you go to your BIOS and check that Virtualization is enabled.

Now install Git on your system with the link above, it's pretty straight forward and you shouldn't have any major problems with it.

Then install GNU make, I will not explain it, just follow this video and you are good to go.

Third install Virtual Box, you will not use it, but it's necessary because this approach use virtualization behind the scenes to make docker works.

Finally install docker toolbox, with the instructions that appear on the page.

Now open the docker start terminal, run

$ docker -v
$ docker-compose -v
$ make -v
$ git -v

And check if everything is installed. Now let's check if the containers and images run as expected. On that command prompt use:

$ docker run hello-world

If you see the output as in these page says, you have everything setted up, follow the instruccions above of how to install the project with this terminal and you should be good to go!

Now the server doesn't work with localhost with these method, you have to enter into the IP of your docker machine. To see this run on the docker toolbox terminal:

docker-machine ls

And copy only the IP of the default machine, without the port.

So this one is a little bit more difficult that the last one, but I strongly recommend it. Why? You will have a Linux kernel on windows, and that will get away all future headaches that a project might give you (or that low level courses, like Operating Systems can give you).

Okay first, you have to set up WSL, this is Linux Subsystem for Windows. I recommend to follow this video, or the microsoft's guide, on the second one run a powershell as an administrator with the command:

Start-Process powershell -Verb runAs

When you have WSL installed, upgrade it to WSL 2. The best guide to follow is the official one from microsoft, you will probable upgrade windows on the process, so this could take a while.

Then you can move the distro to use WSL 2 with:

wsl --set-version <distribution name> <versionNumber>

Finally install docker desktop, with these link instructions.

Open your wsl 2 command prompt and follow the instructions above!, there is nothing more to install and you have a linux kernel in your windows machine :).

In either of these approaches, there could be an issue with the easyexam command, if so, on the folder of the project run:

$ git checkout -- .

Windows add some weird formatting when downloading the project, with these you should be good to go.

You can use jupyter on the backend if you want, to run it do:

easyexam jupyter

And select django shell plus as interpreter

If you want to change some settings but doesn't need to have it on the development environment, on the EasyExamAPI.settings module you can add a file local.py which is by default ignored for git. This has to import all the settings of the development one in order to work, so your file should always begin with:

# local.py in the settings module
from .development import *

For example a common thing to do is change the renderer to a browsable API, then your file:

from .development import *
REST_FRAMEWORK["DEFAULT_RENDERER_CLASSES"] = (
    "rest_framework.renderers.BrowsableAPIRenderer,
)

If any settings change that you want to perform doesn't have to be for everyone, put that change (by overriding the variable or adding some things) on the local.py setting file.

To run unittest on your local machine, on the docker terminal run the command:

$ easyexam test

This will run all the test (frontend and backend) on the container. Currently there is only backend tests, so to run only those you can do:

$ easyexam backend-test

If you want to run a particular test suit, you can run the command:

$ easyexam backend-test <test-suite-import-path>

For example:

$ easyexam backend-test apps.exam.tests.test_views.test_exam

If you want to run only a class for that suite:

$ easyexam backend-test apps.exam.tests.test_views.test_exam::TestExamCreateView

And if you want to run only a method of that suite:

$ easyexam backend-test apps.exam.tests.test_views.test_exam::TestExamCreateView::test_create_exam_anonymous

WARNING This will delete the database mounted on the docker container, so be carefull to not lose the data. You should avoid these at all cost.

If you want to reset your docker image of the project and re mounted, run:

$ make docker-reset

This will add all pre recorded data, if a model change pls change the pre recorded data also.

The common developing branch is development. On this branch all the newest changes are being made and the QA is being performed. All the QA must pass to an issue of a bug or a non existant feature.

Finally, to merge into the development branch, you need to create a pull request and it needs to be approved by, at least, one other teammate and pass the CI github action.

At the end of every sprint, a merge to master will be done or if a common developing feature is added to develop is going to be cherry-picked to master as well.

The deployment process into the buho server is a little bit trickier than heroku because it's not automatic by just merging into one branch and done.

First of all make a merge with no fast forward into the master branch on your local machine. To do this do the following:

(development) git pull
(development) git checkout master
(master) git pull
(master) git merge development --no-ff
(master) git push

Then connect to the buho server and navigate to the easyexamv2 folder:

cd easyexamv2/EasyExam/

Here stash the changes because there are some configurations changes made on the Dockerfile and the worker for the security purpose.

git stash

Then pull the latest master commit

git pull origin master

Pop the latest changes on the stash:

git stash pop

Resolve the conflicts if there is any, but prefer the stashes ones.

And finally reset the docker image:

source venv/bin/activate
make docker-production-reset

Now the buho server have the latest changes of the master branch. Notice that on production the application runs on the port natively on the port 8888 so make the changes necessary on the Dockerfile or the docker-compose.yml in order to achieve the run on that port.

If you want to see the logs of the processes, there is the makefile command:

make docker-logs

Important: NEVER delete the gunicorn command of the Dockerfile and NEVER delete the celery command of the Dockerfile.worker. They are crucial to production.

• It is not possible to attach images to the problems in the current platform.
• There are no new interfaces for the admin to manage the data of the application, instead of that, the django admin’s interfaces are used.
• There is neither a button nor a feature to import .tex files as problems.
• Cloned problems do not store a reference to the original problem from where they were cloned.
• There is not a way to preview the exam in the different versions on the platform, instead of that, it is possible to see them through the download.
• There is not a way to ban users using the platform interfaces.

• There is no cloning button in the “my questions” interface.
• There is no validation data in Problem form.
• There is no a Page Error for handle 404 Errors.
• Default value for date and time input in Exam Form may not work in all browsers.
• If the script fails to compile the LaTeX code, the temporal files generated are not deleted from the platform.

• celery
• redis
• redis_and_celery
• django_jupyter