diff options
| -rw-r--r-- | README_production.md | 228 | ||||
| -rw-r--r-- | README_production.rst | 271 |
2 files changed, 271 insertions, 228 deletions
diff --git a/README_production.md b/README_production.md deleted file mode 100644 index 1251ce0..0000000 --- a/README_production.md +++ /dev/null @@ -1,228 +0,0 @@ -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'. - -#### Installation & Usage - -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. - - You can also use a Dockerized code server (see below) - - 1. Now, Run: - - python manage.py runserver <desired_ip>:<desired_port> - - 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'. - -#### Using Dockerized Code Server - - 1. Install [Docker](https://github.com/FOSSEE/online_test/blob/master/README.md) - - 1. Go to the directory where the project is located - cd /path/to/online_test - - 1. Create a docker image. This may take a few minutes - docker build -t yaksh_code_server . - - 1. Check if the image has been created using the output of, - docker images - - 1. Run the invoke script using the command ```invoke start``` - The command will create and run a new docker container (that is running the code_server.py within it), it will also bind the ports of the host with those of the container - -#### Deploying Multiple Dockers - - 1. Install [Docker](https://github.com/FOSSEE/online_test/blob/master/README.md) - - 1. Go to the ```docker``` directory - - 1. Build the docker images - invoke build - - 1. Run the containers and scripts necessary to deploy the web application - invoke deploy - - Use ```invoke deploy --fixtures``` to load the fixtures - - 1. Create the superuser and moderator group - invoke createsuperuser - - 1. Stop the containers - invoke halt - - 1. Remove the containers - invoke clean - -#### 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/README_production.rst b/README_production.rst new file mode 100644 index 0000000..dec2034 --- /dev/null +++ b/README_production.rst @@ -0,0 +1,271 @@ +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 +2. Install dependencies using pip install -r requirements.txt +3. Install MySql Server +4. Install Python MySql support +5. 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 + +2. Add a user named ``yaksh_user`` and give access to it on the database + ``yaksh`` by following the steps below + + :: + + mysql> grant usage on yaksh to yaksh_user@localhost identified + by 'mysecretpassword'; + + mysql> grant all privileges on yaksh to yaksh_user@localhost; + +3. 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 + +2. Run: + + :: + + python manage.py makemigrations yaksh + + python manage.py migrate yaksh + +4. 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. + +5. 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/ + +6. Go to http://desired\_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 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. + +11. You may dump the results and user data using the results2csv and + dump\_user\_data commands. + +12. The file docs/sample\_questions.py is a template that you can use + for your own questions. + +13. 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'. + +Installation & Usage +^^^^^^^^^^^^^^^^^^^^ + +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`` + +2. Run: + + :: + + $ python manage.py makemigrations yaksh + + $ python manage.py migrate yaksh + +3. Run the python server provided. This ensures that the code is + executed in a safe environment. Do this like so: + + :: + + $ sudo python -m yaksh.code_server # For Python 2.x + + + $ sudo python3 -m yaksh.code_server # For Python 3.x + + 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 the number + ports configured in the settings.py file in the variable + "N\_CODE\_SERVERS". 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. + + You can also use a Dockerized code server (see below) + +4. Now, Run: + + :: + + python manage.py runserver <desired_ip>:<desired_port> + +5. Create a Superuser/Administrator: + + :: + + python manage.py createsuperuser + +6. Go to http://desired\_host\_or\_ip:desired\_port/exam + + And you should be all set. + +7. 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. + +8. As admin user you can visit http://desired\_host\_or\_ip/exam/monitor to view results + and user data interactively. You could also "grade" the papers + manually if needed. + +Using Dockerized Code Server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Install + `Docker <https://docs.docker.com/engine/installation/>`__ + +2. Go to the directory where the project is located cd + /path/to/online\_test + +3. Create a docker image. This may take a few minutes docker build -t + yaksh\_code\_server ./docker/Dockerfile\_codeserver + +4. Check if the image has been created using the output of, docker + images + +5. Run the invoke script using the command ``invoke start`` The command + will create and run a new docker container (that is running the + code\_server.py within it), it will also bind the ports of the host + with those of the container + +Deploying Multiple Dockers +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Install + `Docker <https://docs.docker.com/engine/installation/>`__ + +2. Go to the directory where the project is located at: + + :: + + cd /path/to/online_test + +3. Build the docker images + + :: + + invoke build + +4. Run the containers and scripts necessary to deploy the web + application + + :: + + invoke deploy + +5. Use ``invoke deploy --fixtures`` to load the fixtures + +6. Create the superuser and moderator group + :: + + invoke createsuperuser + +7. Stop the containers + + :: + + invoke halt + +8. Remove the containers + + :: + + invoke clean + + +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. |