From 5203ce57f2a08fe9aef8b97b569855fa9cd50ba4 Mon Sep 17 00:00:00 2001 From: ankitjavalkar Date: Tue, 6 Oct 2015 16:29:45 +0530 Subject: Clean setup procedure - Make corresponding app name changes in script - Change app name in setup.py - Minor changes in Readme, it is now split into quickstart & production - rename install script --- README.md | 220 +++++-------------------------------------------- README_production.md | 189 ++++++++++++++++++++++++++++++++++++++++++ setup.py | 6 +- yaksh/scripts/cli.py | 149 +++++++++++++++++++++++++++++++++ yaksh/scripts/yaksh.py | 147 --------------------------------- 5 files changed, 361 insertions(+), 350 deletions(-) create mode 100644 README_production.md create mode 100644 yaksh/scripts/cli.py delete mode 100644 yaksh/scripts/yaksh.py diff --git a/README.md b/README.md index 45c3e4f..edc4d33 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Yaksh ======== [![Build Status](https://travis-ci.org/FOSSEE/online_test.svg?branch=master)](https://travis-ci.org/FOSSEE/online_test) +This is a Quickstart guide to help users setup a trial instance. If you wish to deploy Yaksh in a production environment here is a [Production Deployment Guide] (https://github.com/FOSSEE/online_test/blob/master/README_production.md) + #### Introduction This project provides an "exam" app that lets users take an online @@ -29,22 +31,28 @@ Quick Start #### Installation 1. Install the yaksh + - For latest stable release - pip install yaksh + pip install yaksh + + - For the development version + + pip install git+https://github.com/FOSSEE/online_test.git 1. In the terminal run - yaksh create_demo [-p PATH] project_name - - ```project_name``` is the desired name of the django project - - PATH is an optional argument to specify where the django project will be installed + yaksh create_demo [-p PATH] [project_name] + - ```project_name``` is the desired name of the django project. + - In case a ```project_name``` is not specified, the project is initialised with the name ```yaksh_demo``` + - PATH is an optional flag to specify where the django project will be installed - If PATH is not provided, the project is created in the current directory 1. The script does the following; - 1. Creates a new django project called `projectname` - 1. Creates a new demo database - 1. Creates two users, test moderator and test examinee - 1. Loads demo questions - 1. Loads demo quiz + 1. Creates a new django project called `project_name` + 1. Creates a new demo database + 1. Creates two users, test moderator and test examinee + 1. Loads demo questions + 1. Loads demo quiz 1. Run: @@ -57,197 +65,9 @@ Quick Start 1. Open your browser and open the URL ```http://localhost:8000/exam``` 1. Login as a teacher to edit the quiz or as a student to take the quiz - Credentials: - - Student - Username: student | Password: student - - Teacher - Username: teacher | Password: teacher - -Production Deployment -====================== - -#### Pre-Requisite - - 1. Install dependencies using - pip install -r requirements.txt - 1. Install MySql Server - 1. Install Python MySql support - 1. Install Apache Server for deployment - -#### Configure MySql server - - 1. Create a database named ``yaksh`` by following the steps below - - $> mysql -u root -p - mysql> create database yaksh - - 1. Add a user named ```yaksh_user``` and give access to it on the database ```yaksh``` by following the steps below - - 1. mysql> grant usage on yaksh.* to yaksh_user@localhost identified by 'mysecretpassword'; - - 1. mysql> grant all privileges on yaksh.* to yaksh_user@localhost; - - 1. Add `DATABASE_PASSWORD = 'mysecretpassword'` and `DATABASE_USER = 'yaksh_user'` to online_test/settings.py - -To deploy this app follow the steps below: - - 1. Clone this repository and cd to the cloned repo. - git clone https://github.com/FOSSEE/online_test.git - - 1. Run: - python manage.py syncdb - - 1. Add questions by editing the "docs/sample_questions.py" or any other file in the same format and then run the following: - - python manage.py 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. - - 1. First run the python server provided. This ensures that the code is executed in a safe environment. Do this like so: - - $ sudo python yaksh/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. - - 1. The ```wsgi.py``` script should make it - easy to deploy this using mod_wsgi. You will need to add a line of the form: - - WSGIScriptAlias / "/online_test/wsgi.py" - - to your apache.conf. For more details see the Django docs here: - - https://docs.djangoproject.com/en/1.6/howto/deployment/wsgi/ - - 1. Go to http://desired_host_or_ip:desired_port/admin - - 1. 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. - - 1. Now ask users to login at: - - http://host:port/exam - - And you should be all set. - - 1. 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. - - 1. As Moderator user you can visit http://host/exam/monitor to view - results and user data interactively. You could also "grade" the - papers manually if needed. - - 1. You may dump the results and user data using the results2csv and - dump_user_data commands. - - 1. The file docs/sample_questions.py is a template that you can use for your own questions. - - 1. 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 -==================== - -To install this app follow the steps below: - - 1. Clone this repository and cd to the cloned repo. - ```git clone https://github.com/FOSSEE/online_test.git``` - - 1. Run: - - python manage.py syncdb - - 1. Add questions by editing the "docs/sample_questions.py" or any other file in the same format and then run the following: - - python manage.py 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. - - 1. First run the python server provided. This ensures that the code is executed in a safe environment. Do this like so: - - $ sudo python yaksh/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. - - 1. Now, Run: - - python manage.py runserver : - - 1. Go to http://desired_host_or_ip:desired_port/admin - - 1. 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. - - 1. Now ask users to login at: - - http://host:port/exam - - And you should be all set. - - 1. 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. - - 1. 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. - - 1. You may dump the results and user data using the results2csv and - dump_user_data commands. - - 1. The file docs/sample_questions.py is a template that you can use for your own questions. - - 1. 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 -============================== - -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: - - $ python manage.py help [command] - -where [command] is one of the above. - + Credentials: + - Student - Username: student | Password: student + - Teacher - Username: teacher | Password: teacher Inspiration =========== diff --git a/README_production.md b/README_production.md new file mode 100644 index 0000000..e7b99e1 --- /dev/null +++ b/README_production.md @@ -0,0 +1,189 @@ +Production Deployment +====================== + +This README provides documentation to help deploy Yaksh in a production environment. If you wish to take Yaksh on a trial run, here is a [Quickstart Guide] (https://github.com/FOSSEE/online_test/blob/master/README.md) + +#### Pre-Requisite + + 1. Ensure [pip](https://pip.pypa.io/en/latest/installing.html) is installed + 1. Install dependencies using + pip install -r requirements.txt + 1. Install MySql Server + 1. Install Python MySql support + 1. Install Apache Server for deployment + +#### Configure MySql server + + 1. Create a database named ``yaksh`` by following the steps below + + $> mysql -u root -p + mysql> create database yaksh + + 1. Add a user named ```yaksh_user``` and give access to it on the database ```yaksh``` by following the steps below + + 1. mysql> grant usage on yaksh.* to yaksh_user@localhost identified by 'mysecretpassword'; + + 1. mysql> grant all privileges on yaksh.* to yaksh_user@localhost; + + 1. Add `DATABASE_PASSWORD = 'mysecretpassword'` and `DATABASE_USER = 'yaksh_user'` to online_test/settings.py + +To deploy this app follow the steps below: + + 1. Clone this repository and cd to the cloned repo. + git clone https://github.com/FOSSEE/online_test.git + + 1. Run: + python manage.py syncdb + + 1. Add questions by editing the "docs/sample_questions.py" or any other file in the same format and then run the following: + + python manage.py 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. + + 1. First run the python server provided. This ensures that the code is executed in a safe environment. Do this like so: + + $ sudo python yaksh/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. + + 1. The ```wsgi.py``` script should make it + easy to deploy this using mod_wsgi. You will need to add a line of the form: + + WSGIScriptAlias / "/online_test/wsgi.py" + + to your apache.conf. For more details see the Django docs here: + + https://docs.djangoproject.com/en/1.6/howto/deployment/wsgi/ + + 1. Go to http://desired_host_or_ip:desired_port/admin + + 1. 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. + + 1. Now ask users to login at: + + http://host:port/exam + + And you should be all set. + + 1. 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. + + 1. As Moderator user you can visit http://host/exam/monitor to view + results and user data interactively. You could also "grade" the + papers manually if needed. + + 1. You may dump the results and user data using the results2csv and + dump_user_data commands. + + 1. The file docs/sample_questions.py is a template that you can use for your own questions. + + 1. 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 +==================== + +To install this app follow the steps below: + + 1. Clone this repository and cd to the cloned repo. + ```git clone https://github.com/FOSSEE/online_test.git``` + + 1. Run: + + python manage.py syncdb + + 1. Add questions by editing the "docs/sample_questions.py" or any other file in the same format and then run the following: + + python manage.py 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. + + 1. First run the python server provided. This ensures that the code is executed in a safe environment. Do this like so: + + $ sudo python yaksh/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. + + 1. Now, Run: + + python manage.py runserver : + + 1. Go to http://desired_host_or_ip:desired_port/admin + + 1. 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. + + 1. Now ask users to login at: + + http://host:port/exam + + And you should be all set. + + 1. 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. + + 1. 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. + + 1. You may dump the results and user data using the results2csv and + dump_user_data commands. + + 1. The file docs/sample_questions.py is a template that you can use for your own questions. + + 1. 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 +============================== + +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: + + $ python manage.py help [command] + +where [command] is one of the above. diff --git a/setup.py b/setup.py index 839607e..45227d1 100644 --- a/setup.py +++ b/setup.py @@ -7,8 +7,8 @@ README = open(os.path.join(os.path.dirname(__file__), 'README.md')).read() os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir))) setup( - name='django-exam', - author='python team at IIT Bombay', + name='yaksh', + author='Python Team, IIT Bombay', author_email='python@fossee.in', version='0.1', packages=find_packages(), @@ -16,7 +16,7 @@ setup( license='BSD License', entry_points = { 'console_scripts': [ - 'yaksh = yaksh.scripts.yaksh:main', + 'yaksh = yaksh.scripts.cli:main', ], }, description='A django app to conduct online tests.', diff --git a/yaksh/scripts/cli.py b/yaksh/scripts/cli.py new file mode 100644 index 0000000..5ad5ad6 --- /dev/null +++ b/yaksh/scripts/cli.py @@ -0,0 +1,149 @@ +from __future__ import print_function + +import subprocess +import contextlib +import os +from os import path +import argparse +from importlib import import_module +from django.conf import settings +from django.core import management +from django.template import Template, Context, loader + +from project_detail import NAME, PATH + +CUR_DIR = os.getcwd() +SCRIPT_DIR = os.path.abspath(os.path.dirname(__file__)) +PARENT_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, os.pardir)) +TEMPLATE_DIR = path.join(PARENT_DIR, 'demo_templates') + +def main(): + #Parse command-line to obtain the arguments and/or options + # create top-level parser object + parser = argparse.ArgumentParser(prog="yaksh") + subparser = parser.add_subparsers(dest="subcommand") + + # create parser for the "create_demo" subcommand + create_demo_parser = subparser.add_parser("create_demo", + help="Create a new demo Django project") + create_demo_parser.add_argument("project_name", type=str, + default="yaksh_demo", + nargs="?", + help="name of demo Django project") + create_demo_parser.add_argument("-p", "--path", type=str, + help="path of demo Django project") + + # create parser for the "run_demo" subcommand + run_demo_parser = subparser.add_parser("run_demo", + help="Initialise django server and run the demo project") + + # create parser for the "run_code_server" subcommand + code_server_parser = subparser.add_parser("run_code_server", + help="Initialise yaksh code server") + code_server_parser.add_argument("-P", "--ports", type=int, nargs='+', + help="code server ports") + + args = parser.parse_args() + + if args.subcommand == "create_demo": + if args.path: + create_demo(args.project_name, args.path) + else: + create_demo(args.project_name) + + elif args.subcommand == "run_demo": + try: + run_demo(NAME, PATH) + except Exception as e: + if not NAME or not PATH: + print("Error: Unable to find Project Name or Path variables\n") + else: + print("Error: {0}\n".format(e)) + subparser.print_help() + + elif args.subcommand == "run_code_server": + if args.ports: + run_server(args.ports) + else: + run_server() + +def create_demo(project_name='yaksh_demo', project_dir=CUR_DIR): + try: + management.call_command('startproject', project_name, project_dir) + print("Demo Django project '{0}' created at '{1}'".format(project_name, + project_dir)) + except Exception, e: + print("Error: {0}\nExiting yaksh Installer".format(e)) + + if project_dir is None: + top_dir = path.join(os.getcwd(), project_name) + else: + top_dir = project_dir + + project_path = path.join(top_dir, project_name) + fixture_dir = path.join(PARENT_DIR, 'fixtures') + # Store project details + _set_project_details(project_name, top_dir) + + with _chdir(project_path): + root_urlconf = "{0}.{1}".format(project_name, 'demo_urls') + settings_template_path = path.join(TEMPLATE_DIR, 'demo_settings.py') + settings_target_path = path.join(project_path, 'demo_settings.py') + settings_context = Context({'project_name': project_name, + 'root_urlconf': root_urlconf, + 'fixture_dir': fixture_dir}) + urls_template_path = path.join(TEMPLATE_DIR, 'demo_urls.py') + urls_target_path = path.join(project_path, 'demo_urls.py') + command = ("python ../manage.py syncdb " + "--noinput --settings={0}.demo_settings").format(project_name) + + # Create demo_settings file + _render_demo_files(settings_template_path, settings_target_path, settings_context) + # Create demo_urls file + _render_demo_files(urls_template_path, urls_target_path) + # Run syncdb + subprocess.call(command, shell=True) + +def run_demo(project_name, top_dir): + with _chdir(top_dir): + project_path = path.join(top_dir, 'manage.py') + command = ("python manage.py runserver " + "--settings={0}.demo_settings").format(project_name) + subprocess.call(command, shell=True) + +def run_server(): + # try: + from yaksh import code_server + code_server.main() + # except Exception as e: + print("Error: {0}\nExiting yaksh code server".format(e)) + +def _set_project_details(project_name, top_dir): + file_path = path.join(SCRIPT_DIR, 'project_detail.py') + detail = "NAME ='{0}'\nPATH ='{1}'".format(project_name, top_dir) + with open(file_path, 'w') as data_store: + data_store.write(detail) + +def _render_demo_files(template_path, output_path, context=None): + with open(template_path, 'r') as template_file: + content = template_file.read() + if context: + content = content.decode('utf-8') + template = Template(content) + content = template.render(context) + content = content.encode('utf-8') + + with open(output_path, 'w') as new_file: + new_file.write(content) + +@contextlib.contextmanager +def _chdir(path): + starting_directory = os.getcwd() + try: + os.chdir(path) + yield + finally: + os.chdir(starting_directory) + +if __name__ == '__main__': + main() diff --git a/yaksh/scripts/yaksh.py b/yaksh/scripts/yaksh.py deleted file mode 100644 index 4360d1b..0000000 --- a/yaksh/scripts/yaksh.py +++ /dev/null @@ -1,147 +0,0 @@ -from __future__ import print_function - -import subprocess -import contextlib -import os -from os import path -import argparse -from importlib import import_module -from django.conf import settings -from django.core import management -from django.template import Template, Context, loader - -from project_detail import NAME, PATH - -CUR_DIR = os.getcwd() -SCRIPT_DIR = os.path.abspath(os.path.dirname(__file__)) -PARENT_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, os.pardir)) -TEMPLATE_DIR = path.join(PARENT_DIR, 'demo_templates') - -def main(): - #Parse command-line to obtain the arguments and/or options - # create top-level parser object - parser = argparse.ArgumentParser(prog="vimarsh") - subparser = parser.add_subparsers(dest="subcommand") - - # create parser for the "create_demo" subcommand - create_demo_parser = subparser.add_parser("create_demo", - help="Create a new demo Django project") - create_demo_parser.add_argument("project_name", type=str, - help="name of demo Django project") - create_demo_parser.add_argument("-p", "--path", type=str, - help="path of demo Django project") - - # create parser for the "run_demo" subcommand - run_demo_parser = subparser.add_parser("run_demo", - help="Initialise django server and run the demo project") - - # create parser for the "run_code_server" subcommand - code_server_parser = subparser.add_parser("run_code_server", - help="Initialise Vimarsh code server") - code_server_parser.add_argument("-P", "--ports", type=int, nargs='+', - help="code server ports") - - args = parser.parse_args() - - if args.subcommand == "create_demo": - if args.path: - create_demo(args.project_name, args.path) - else: - create_demo(args.project_name) - - elif args.subcommand == "run_demo": - try: - run_demo(NAME, PATH) - except Exception as e: - if not NAME or not PATH: - print("Error: Unable to find Project Name or Path variables\n") - else: - print("Error: {0}\n".format(e)) - subparser.print_help() - - elif args.subcommand == "run_code_server": - if args.ports: - run_server(args.ports) - else: - run_server() - -def create_demo(project_name='vimarsh_demo', project_dir=CUR_DIR): - try: - management.call_command('startproject', project_name, project_dir) - print("Demo Django project '{0}' created at '{1}'".format(project_name, - project_dir)) - except Exception, e: - print("Error: {0}\nExiting Vimarsh Installer".format(e)) - - if project_dir is None: - top_dir = path.join(os.getcwd(), project_name) - else: - top_dir = project_dir - - project_path = path.join(top_dir, project_name) - fixture_dir = path.join(PARENT_DIR, 'fixtures') - # Store project details - _set_project_details(project_name, top_dir) - - with _chdir(project_path): - root_urlconf = "{0}.{1}".format(project_name, 'demo_urls') - settings_template_path = path.join(TEMPLATE_DIR, 'demo_settings.py') - settings_target_path = path.join(project_path, 'demo_settings.py') - settings_context = Context({'project_name': project_name, - 'root_urlconf': root_urlconf, - 'fixture_dir': fixture_dir}) - urls_template_path = path.join(TEMPLATE_DIR, 'demo_urls.py') - urls_target_path = path.join(project_path, 'demo_urls.py') - command = ("python ../manage.py syncdb " - "--noinput --settings={0}.demo_settings").format(project_name) - - # Create demo_settings file - _render_demo_files(settings_template_path, settings_target_path, settings_context) - # Create demo_urls file - _render_demo_files(urls_template_path, urls_target_path) - # Run syncdb - subprocess.call(command, shell=True) - -def run_demo(project_name, top_dir): - with _chdir(top_dir): - project_path = path.join(top_dir, 'manage.py') - command = ("python manage.py runserver " - "--settings={0}.demo_settings").format(project_name) - subprocess.call(command, shell=True) - -def run_server(): - try: - from yaksh import code_server - code_server.main() - except Exception as e: - print("Error: {0}\nExiting Vimarsh code server".format(e)) - -def _set_project_details(project_name, top_dir): - file_path = path.join(SCRIPT_DIR, 'project_detail.py') - detail = "NAME ='{0}'\nPATH ='{1}'".format(project_name, top_dir) - with open(file_path, 'w') as data_store: - data_store.write(detail) - -def _render_demo_files(template_path, output_path, context=None): - with open(template_path, 'r') as template_file: - content = template_file.read() - if context: - content = content.decode('utf-8') - template = Template(content) - content = template.render(context) - content = content.encode('utf-8') - - with open(output_path, 'w') as new_file: - new_file.write(content) - -@contextlib.contextmanager -def _chdir(path): - starting_directory = os.getcwd() - try: - os.chdir(path) - yield - finally: - os.chdir(starting_directory) - -if __name__ == '__main__': - main() -- cgit