From b49fbfe2f3438f6d59af36de416cf9b7f33723ab Mon Sep 17 00:00:00 2001 From: parth Date: Fri, 9 Dec 2011 05:20:46 +0530 Subject: Changed README.txt to README.rst --- README.rst | 241 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 README.rst (limited to 'README.rst') diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..75d3061 --- /dev/null +++ b/README.rst @@ -0,0 +1,241 @@ +Introduction +============ + +This app provides an "exam" app that lets users take an online +programming quiz. Currently only Python and simple Bash scripts can be +tested. At FOSSEE, Nishanth had implemented a nice django based app to +test for multiple-choice questions. However, I was inspired by a +programming contest that I saw at PyCon APAC 2011. Chris Boesch, who +administered the contest, used a nice web application that he had built +on top of GAE that basically checked your Python code, live. This made +it fun and interesting. Their application can be seen at +http://singpath.com + +I wanted an implementation that was not tied to GAE and decided to write +one myself and the result is the "exam" app. The idea being that I can +use this to test students programming skills and not have to worry about +grading their answers myself and I can do so on my machines. + +You can define fairly complicated programming problems and have users +solve the problem and the solution is checked immediately. The system +supports pretty much arbitrary Python and uses "test cases" to test the +implementations of the students. It also supports simple bash scripts +-- see the sample questions in "docs/". In addition it supports simple +multiple choice questions. Since it runs on your Python, you could +technically test any Python based library. It is distributed under the +BSD license. + +It can use a lot more work but the basics work and the app scales to +over 500+ simultaneous users. :) + +Pre-Requisite +============= + + 1. Install MySql Server + + 2. Install Python MySql support + + 3. Install Apache Server for deployment + +Configure MySql server +---------------------- + + 1. Create a database named `online_test` + + 2. Add a user named `online_test_user` and give access to it on the database `online_test` + + 3. Create a file named `local.py` in folder `testapp` and insert `DATABASE_PASSWORD = 'yourpassword'` + + +Production Deployment +===================== + +To install/deploy this app follow the steps below: + + 1. Clone this repository and cd to the cloned repo. + + 2. run python bootstrap.py + + 3. run ./bin/buildout -c production.cfg + + 4. run ./bin/django syncdb + [ enter password etc.] + + run ./bin/django migrate exam + + 5. Add questions by editing the "docs/sample_questions.py" or any other + file in the same format and then run the following:: + + ./bin/django load_exam docs/sample_questions.py + + Note that you can supply multiple Python files as arguments and all of + those will be added to the database. + + 4. First run the python server provided. This ensures that the code is + executed in a safe environment. Do this like so:: + + $ sudo python testapp/code_server.py + + Put this in the background once it has started since this will not + return back the prompt. It is important that the server be running + *before* students start attempting the exam. Using sudo is + necessary since the server is run as the user "nobody". This runs + on the ports configured in the settings.py file in the variable + "SERVER_PORTS". The "SERVER_TIMEOUT" also can be changed there. + This is the maximum time allowed to execute the submitted code. + Note that this will likely spawn multiple processes as "nobody" + depending on the number of server ports specified. + + 5. The ``bin/django.wsgi`` script should make it + easy to deploy this using mod_wsgi. You will need to add a line of the form: + + WSGIScriptAlias / "/var/www/online_test/bin/django.wsgi" + + to your apache.conf. For more details see the Django docs here: + + https://docs.djangoproject.com/en/1.3/howto/deployment/modwsgi/ + + 6. Go to http://deserved_host_or_ip:desired_port/admin + + 7. Login with your credentials and look at the questions and modify if + needed. Create a new Quiz, set the date and duration or + activate/deactivate the quiz. + + 8. Now ask users to login at: + + http://host:port/exam + + And you should be all set. + + 9. Note that the directory "output" will contain directories, one for each + user. Users can potentially write output into these that can be used + for checking later. + + 10. As admin user you can visit http://host/exam/monitor to view + results and user data interactively. You could also "grade" the + papers manually if needed. + + 11. You may dump the results and user data using the results2csv and + dump_user_data commands. + +Development Settings +==================== + +To install/deploy this app follow the steps below: + + 1. Clone this repository and cd to the cloned repo. + + 2. run python bootstrap.py + + 3. run ./bin/buildout -c buildout.cfg + + 4. run ./bin/django syncdb + [ enter password etc.] + + run ./bin/django migrate exam + + 5. Add questions by editing the "docs/sample_questions.py" or any other + file in the same format and then run the following:: + + ./bin/django load_exam docs/sample_questions.py + + Note that you can supply multiple Python files as arguments and all of + those will be added to the database. + + 4. First run the python server provided. This ensures that the code is + executed in a safe environment. Do this like so:: + + $ sudo python testapp/code_server.py + + Put this in the background once it has started since this will not + return back the prompt. It is important that the server be running + *before* students start attempting the exam. Using sudo is + necessary since the server is run as the user "nobody". This runs + on the ports configured in the settings.py file in the variable + "SERVER_PORTS". The "SERVER_TIMEOUT" also can be changed there. + This is the maximum time allowed to execute the submitted code. + Note that this will likely spawn multiple processes as "nobody" + depending on the number of server ports specified. + + 5. Now, run:: + + $ ./bin/django runserver : + + 6. Go to http://deserved_host_or_ip:desired_port/admin + + 7. Login with your credentials and look at the questions and modify if + needed. Create a new Quiz, set the date and duration or + activate/deactivate the quiz. + + 8. Now ask users to login at: + + http://host:port/exam + + And you should be all set. + + 9. Note that the directory "output" will contain directories, one for each + user. Users can potentially write output into these that can be used + for checking later. + + 10. As admin user you can visit http://host/exam/monitor to view + results and user data interactively. You could also "grade" the + papers manually if needed. + + 11. You may dump the results and user data using the results2csv and + dump_user_data commands. + + +The file docs/sample_questions.py is a template that you can use for your +own questions. + +Additional commands available +============================== + +We provide several convenient commands for you to use: + + - load_exam : load questions and a quiz from a python file. See + docs/sample_questions.py + + - load_questions_xml : load questions from XML file, see + docs/sample_questions.xml use of this is deprecated in favor of + load_exam. + + - results2csv : Dump the quiz results into a CSV file for further + processing. + + - dump_user_data : Dump out relevalt user data for either all users or + specified users. + +For more information on these do this:: + + $ ./manage.py help [command] + +where [command] is one of the above. + +License +======= + +This is distributed under the terms of the BSD license. Copyright +information is at the bottom of this file. + +Authors +======= + +Main author: Prabhu Ramachandran + +I gratefully acknowledge help from the following: + + - Nishanth Amuluru originally from FOSSEE who wrote bulk of the + login/registration code. He wrote an initial first cut of a quiz app + which supported only simple questions which provided motivation for + this app. The current codebase does not share too much from his + implementation although there are plenty of similarities. + + - Harish Badrinath (FOSSEE) -- who provided a first cut of the bash + related scripts. + + - Srikant Patnaik and Thomas Stephen Lee, who helped deploy and test + the code. + + +Copyright (c) 2011 Prabhu Ramachandran and FOSSEE (fossee.in) \ No newline at end of file -- cgit From 5c20e867622cd72debae13cdbd1240b0c5588e5a Mon Sep 17 00:00:00 2001 From: parth Date: Fri, 9 Dec 2011 05:27:57 +0530 Subject: made some modifications to the readme file --- README.rst | 108 ++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 61 insertions(+), 47 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 75d3061..784962b 100644 --- a/README.rst +++ b/README.rst @@ -31,48 +31,55 @@ over 500+ simultaneous users. :) Pre-Requisite ============= - 1. Install MySql Server + #. Install MySql Server - 2. Install Python MySql support + #. Install Python MySql support - 3. Install Apache Server for deployment + #. Install Apache Server for deployment Configure MySql server ---------------------- - 1. Create a database named `online_test` + #. Create a database named ``online_test`` - 2. Add a user named `online_test_user` and give access to it on the database `online_test` + #. Add a user named ``online_test_user`` and give access to it on the database ``online_test`` - 3. Create a file named `local.py` in folder `testapp` and insert `DATABASE_PASSWORD = 'yourpassword'` + #. Create a file named `local.py` in folder `testapp` and insert `DATABASE_PASSWORD = 'yourpassword'` Production Deployment ===================== -To install/deploy this app follow the steps below: +To deploy this app follow the steps below: - 1. Clone this repository and cd to the cloned repo. + #. Clone this repository and cd to the cloned repo. - 2. run python bootstrap.py + #. run:: - 3. run ./bin/buildout -c production.cfg + python bootstrap.py - 4. run ./bin/django syncdb - [ enter password etc.] + #. run:: - run ./bin/django migrate exam + ./bin/buildout -c production.cfg + + #. run:: + + ./bin/django syncdb + + [ enter password etc.] + + run:: - 5. Add questions by editing the "docs/sample_questions.py" or any other - file in the same format and then run the following:: + ./bin/django migrate exam + + #. Add questions by editing the "docs/sample_questions.py" or any other file in the same format and then run the following:: ./bin/django load_exam docs/sample_questions.py Note that you can supply multiple Python files as arguments and all of those will be added to the database. - 4. First run the python server provided. This ensures that the code is - executed in a safe environment. Do this like so:: + #. First run the python server provided. This ensures that the code is executed in a safe environment. Do this like so:: $ sudo python testapp/code_server.py @@ -86,7 +93,7 @@ To install/deploy this app follow the steps below: Note that this will likely spawn multiple processes as "nobody" depending on the number of server ports specified. - 5. The ``bin/django.wsgi`` script should make it + #. The ``bin/django.wsgi`` script should make it easy to deploy this using mod_wsgi. You will need to add a line of the form: WSGIScriptAlias / "/var/www/online_test/bin/django.wsgi" @@ -95,55 +102,62 @@ To install/deploy this app follow the steps below: https://docs.djangoproject.com/en/1.3/howto/deployment/modwsgi/ - 6. Go to http://deserved_host_or_ip:desired_port/admin + #. Go to http://deserved_host_or_ip:desired_port/admin - 7. Login with your credentials and look at the questions and modify if + #. Login with your credentials and look at the questions and modify if needed. Create a new Quiz, set the date and duration or activate/deactivate the quiz. - 8. Now ask users to login at: + #. Now ask users to login at: http://host:port/exam And you should be all set. - 9. Note that the directory "output" will contain directories, one for each + #. Note that the directory "output" will contain directories, one for each user. Users can potentially write output into these that can be used for checking later. - 10. As admin user you can visit http://host/exam/monitor to view + #. As admin user you can visit http://host/exam/monitor to view results and user data interactively. You could also "grade" the papers manually if needed. - 11. You may dump the results and user data using the results2csv and + #. You may dump the results and user data using the results2csv and dump_user_data commands. Development Settings ==================== -To install/deploy this app follow the steps below: +To install this app follow the steps below: - 1. Clone this repository and cd to the cloned repo. + #. Clone this repository and cd to the cloned repo. + + #. run:: + + python bootstrap.py - 2. run python bootstrap.py + #. run:: - 3. run ./bin/buildout -c buildout.cfg + ./bin/buildout -c production.cfg - 4. run ./bin/django syncdb - [ enter password etc.] + #. run:: - run ./bin/django migrate exam + ./bin/django syncdb + + [ enter password etc.] + + run:: + + ./bin/django migrate exam - 5. Add questions by editing the "docs/sample_questions.py" or any other - file in the same format and then run the following:: + #. Add questions by editing the "docs/sample_questions.py" or any other file in the same format and then run the following:: ./bin/django load_exam docs/sample_questions.py Note that you can supply multiple Python files as arguments and all of those will be added to the database. - 4. First run the python server provided. This ensures that the code is - executed in a safe environment. Do this like so:: + #. First run the python server provided. This ensures that the code is executed in a safe environment. Do this like so:: $ sudo python testapp/code_server.py @@ -157,35 +171,35 @@ To install/deploy this app follow the steps below: Note that this will likely spawn multiple processes as "nobody" depending on the number of server ports specified. - 5. Now, run:: - - $ ./bin/django runserver : + #. Now, run:: + + $ ./bin/django runserver : - 6. Go to http://deserved_host_or_ip:desired_port/admin + #. Go to http://deserved_host_or_ip:desired_port/admin - 7. Login with your credentials and look at the questions and modify if + #. Login with your credentials and look at the questions and modify if needed. Create a new Quiz, set the date and duration or activate/deactivate the quiz. - 8. Now ask users to login at: + #. Now ask users to login at: http://host:port/exam And you should be all set. - 9. Note that the directory "output" will contain directories, one for each + #. Note that the directory "output" will contain directories, one for each user. Users can potentially write output into these that can be used for checking later. - 10. As admin user you can visit http://host/exam/monitor to view + #. As admin user you can visit http://host/exam/monitor to view results and user data interactively. You could also "grade" the papers manually if needed. - 11. You may dump the results and user data using the results2csv and + #. You may dump the results and user data using the results2csv and dump_user_data commands. - - -The file docs/sample_questions.py is a template that you can use for your + + + The file docs/sample_questions.py is a template that you can use for your own questions. Additional commands available -- cgit From bfeb9fd61fb2eb1f8483466270295234b8f17421 Mon Sep 17 00:00:00 2001 From: parth Date: Fri, 9 Dec 2011 05:30:49 +0530 Subject: made some modifications to the readme file --- README.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 784962b..7286bb1 100644 --- a/README.rst +++ b/README.rst @@ -60,13 +60,11 @@ To deploy this app follow the steps below: #. run:: - ./bin/buildout -c production.cfg + ./bin/buildout -c production.cfg #. run:: - ./bin/django syncdb - - [ enter password etc.] + ./bin/django syncdb run:: -- cgit From 54235fd3b2dd188a386056d5811a5370cf8c79fb Mon Sep 17 00:00:00 2001 From: parth Date: Fri, 9 Dec 2011 05:31:57 +0530 Subject: made some modifications to the readme file --- README.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 7286bb1..466f148 100644 --- a/README.rst +++ b/README.rst @@ -140,9 +140,7 @@ To install this app follow the steps below: #. run:: - ./bin/django syncdb - - [ enter password etc.] + ./bin/django syncdb run:: -- cgit From 9c10310bb2e623b3b8b3f13b0d162e2009ad8239 Mon Sep 17 00:00:00 2001 From: parth Date: Fri, 9 Dec 2011 05:33:37 +0530 Subject: made some modifications to the readme file --- README.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 466f148..dc33a1f 100644 --- a/README.rst +++ b/README.rst @@ -195,8 +195,7 @@ To install this app follow the steps below: dump_user_data commands. - The file docs/sample_questions.py is a template that you can use for your -own questions. + The file docs/sample_questions.py is a template that you can use for your own questions. Additional commands available ============================== -- cgit From 364650e602d751d920b8579fb10546a55ed13d38 Mon Sep 17 00:00:00 2001 From: parth Date: Fri, 9 Dec 2011 05:34:17 +0530 Subject: made some modifications to the readme file --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index dc33a1f..64113da 100644 --- a/README.rst +++ b/README.rst @@ -128,7 +128,7 @@ Development Settings To install this app follow the steps below: - #. Clone this repository and cd to the cloned repo. + #. Clone this repository and cd to the cloned repo. #. run:: -- cgit From 4a2cb590dc422345f22e0ad1435ab954d77458a3 Mon Sep 17 00:00:00 2001 From: parth Date: Fri, 9 Dec 2011 05:42:54 +0530 Subject: made some modifications to the readme file --- README.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 64113da..29fcdc3 100644 --- a/README.rst +++ b/README.rst @@ -56,7 +56,7 @@ To deploy this app follow the steps below: #. run:: - python bootstrap.py + python bootstrap.py #. run:: @@ -74,8 +74,8 @@ To deploy this app follow the steps below: ./bin/django load_exam docs/sample_questions.py - Note that you can supply multiple Python files as arguments and all of - those will be added to the database. + Note that you can supply multiple Python files as arguments and all of + those will be added to the database. #. First run the python server provided. This ensures that the code is executed in a safe environment. Do this like so:: @@ -132,11 +132,11 @@ To install this app follow the steps below: #. run:: - python bootstrap.py + python bootstrap.py #. run:: - ./bin/buildout -c production.cfg + ./bin/buildout -c production.cfg #. run:: @@ -150,8 +150,8 @@ To install this app follow the steps below: ./bin/django load_exam docs/sample_questions.py - Note that you can supply multiple Python files as arguments and all of - those will be added to the database. + Note that you can supply multiple Python files as arguments and all of + those will be added to the database. #. First run the python server provided. This ensures that the code is executed in a safe environment. Do this like so:: -- cgit From e43c58cd5baf03a4fb2052f20c867aec5fbf849f Mon Sep 17 00:00:00 2001 From: parth Date: Fri, 23 Dec 2011 00:57:55 +0530 Subject: Made changes to README to include detailed instructions for mysql installation and URL_ROOT as per Prof. Prabhu Ramachandran's sugestions --- README.rst | 43 ++++++++++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 11 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 29fcdc3..72463c3 100644 --- a/README.rst +++ b/README.rst @@ -27,9 +27,13 @@ BSD license. It can use a lot more work but the basics work and the app scales to over 500+ simultaneous users. :) + + +Production Deployment +===================== Pre-Requisite -============= +------------- #. Install MySql Server @@ -40,15 +44,19 @@ Pre-Requisite Configure MySql server ---------------------- - #. Create a database named ``online_test`` + #. Create a database named ``online_test`` by following the steps below + + #. $> mysql -u root -p + + #. mysql> create database online_test - #. Add a user named ``online_test_user`` and give access to it on the database ``online_test`` + #. Add a user named ``online_test_user`` and give access to it on the database ``online_test`` by following the steps below - #. Create a file named `local.py` in folder `testapp` and insert `DATABASE_PASSWORD = 'yourpassword'` - - -Production Deployment -===================== + #. mysql> grant usage on online_test.* to online_test_user@localhost identified by 'mysecretpassword'; + + #. mysql> grant all privileges on online_test.* to online_test_user@localhost; + + #. Create a file named `local.py` in folder `testapp` and insert `DATABASE_PASSWORD = 'mysecretpassword'` To deploy this app follow the steps below: @@ -100,7 +108,7 @@ To deploy this app follow the steps below: https://docs.djangoproject.com/en/1.3/howto/deployment/modwsgi/ - #. Go to http://deserved_host_or_ip:desired_port/admin + #. Go to http://desired_host_or_ip:desired_port/admin #. Login with your credentials and look at the questions and modify if needed. Create a new Quiz, set the date and duration or @@ -122,6 +130,14 @@ To deploy this app follow the steps below: #. You may dump the results and user data using the results2csv and dump_user_data commands. + + #. The file docs/sample_questions.py is a template that you can use for your own questions. + + #. Sometimes you might be in the situation where you are not hosted as + "host.org/exam/" but as "host.org/foo/exam/" for whatever reason. In + this case edit "settings.py" and set the "URL_ROOT" to the root you + have to serve at. In the above example for "host.org/foo/exam" set + URL_ROOT='/foo'. Development Settings ==================== @@ -194,8 +210,13 @@ To install this app follow the steps below: #. You may dump the results and user data using the results2csv and dump_user_data commands. + #. The file docs/sample_questions.py is a template that you can use for your own questions. - The file docs/sample_questions.py is a template that you can use for your own questions. + #. Sometimes you might be in the situation where you are not hosted as + "host.org/exam/" but as "host.org/foo/exam/" for whatever reason. In + this case edit "settings.py" and set the "URL_ROOT" to the root you + have to serve at. In the above example for "host.org/foo/exam" set + URL_ROOT='/foo'. Additional commands available ============================== @@ -247,4 +268,4 @@ I gratefully acknowledge help from the following: the code. -Copyright (c) 2011 Prabhu Ramachandran and FOSSEE (fossee.in) \ No newline at end of file +Copyright (c) 2011 Prabhu Ramachandran and FOSSEE (fossee.in) -- cgit