Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: improve README #56

Merged
merged 7 commits into from
Jun 25, 2024
Merged

docs: improve README #56

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
36492b0
docs: improve readme
dcoa Jun 6, 2024
fc98f15
docs: improve install instructions
dcoa Jun 6, 2024
5c6f9a8
docs: update version syntax in default docker image
dcoa Jun 6, 2024
117440f
docs: update install AppArmor instructions
dcoa Jun 7, 2024
78c58c5
docs: update readme codeblock CODEJAIL_EXTRA_PIP_REQUIREMENTS formatting
dcoa Jun 11, 2024
8331d4b
docs: include custom image section
dcoa Jun 18, 2024
2d25f97
docs: enhance description
dcoa Jun 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 37 additions & 39 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
Codejail plugin for `Tutor`_
============================

Tutor plugin that enables execution of untrusted code in secure sandboxes using an external `service`_ based on the `codejail`_ library.
Tutor plugin that configures and runs Codejail using a REST API service. Codejail allows for the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall I think is good to go, but if you have time can you include the link to the edunext/codejailservice repository?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure

secure execution of untrusted code within sandboxes, providing a safe environment for running potentially dangerous code.

.. _Tutor: https://docs.tutor.overhang.io
.. _service: https://github.com/eduNEXT/codejailservice
Expand All @@ -10,18 +11,27 @@ Tutor plugin that enables execution of untrusted code in secure sandboxes using
Installation
------------

To install the latest version run:

.. code-block:: bash

pip install git+https://github.com/edunext/tutor-contrib-codejail

You can install a specific version by adding the tag, branch, or commit:

.. code-block:: bash

pip install git+https://github.com/edunext/[email protected]

Usage
-----
Enable the plugin with:

.. code-block:: bash

tutor plugins enable codejail

Then, you will have to install the "docker-edx-sandbox" apparmor profile on your host:
Run the initialization jobs to install the required AppArmor profile on your host:

.. code-block:: bash

Expand All @@ -34,13 +44,15 @@ Finally, the platform can be run as usual:

tutor local launch

**Please remember:** If the host is rebooted, the AppArmor profile needs to be reloaded.

Configuration
-------------

For some of these configurations to work correctly, the codejail image must be built again. Command to build codejail: ``tutor images build codejail``.
To customize the configuration, update the following settings in Tutor:

- ``CODEJAIL_APPARMOR_DOCKER_IMAGE``: (default: ``docker.io/ednxops/codejail_apparmor_loader:latest``)
- ``CODEJAIL_DOCKER_IMAGE``: (default: ``docker.io/ednxops/codejailservice:14.0.0``)
- ``CODEJAIL_DOCKER_IMAGE``: (default: ``docker.io/ednxops/codejailservice:{{__version__}}``)
mariajgrimaldi marked this conversation as resolved.
Show resolved Hide resolved
- ``CODEJAIL_ENFORCE_APPARMOR`` (default: ``True``)
- ``CODEJAIL_ENABLE_K8S_DAEMONSET`` (default: ``False``)
- ``CODEJAIL_SKIP_INIT`` (default: ``False``)
Expand All @@ -51,6 +63,8 @@ For some of these configurations to work correctly, the codejail image must be b

CODEJAIL_EXTRA_PIP_REQUIREMENTS:
- pybryt

**NOTE:** For some configurations to work, the codejail image must be rebuilt. Command to rebuild codejail: ``tutor images build codejail``.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we know which configurations merit a new build? Can we add them here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think most people don't build this image, so it should rather be framed as what would require a custom build:

  1. Additional requirements in the sandbox via CODEJAIL_EXTRA_PIP_REQUIREMENTS.
  2. A different version of python for the sandbox environment via CODEJAIL_SANDBOX_PYTHON_VERSION.
  3. Custom version of edx-platform that changes the contents of requirements/edx-sandbox.

One plugin that includes a section like this is tutor-ecommerce.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implemented :)



Compatibility
Expand All @@ -72,64 +86,55 @@ Compatibility
| Quince | >= 17.x |
+------------------+---------------+

**NOTE**: For the Open edx version of the Lilac release, the changes required for the Codejail service to interact with ``edx-platform`` are
not included in ``open-release/lilac.master``. In order to use the service with the changes, please review `this PR`_.
**NOTE**: For the Open edX version of the Lilac release, the changes required for the Codejail service to interact with ``edx-platform`` are
not included in ``open-release/lilac.master``. To use the service with the changes, please review `this PR`_.

.. _this PR: https://github.com/openedx/edx-platform/pull/27795

Kubernetes Support
------------------

The CodeJail service provides a sandbox to run arbitrary code. Security enforcement
in the sandbox is done through AppArmor, this means that AppArmor must be installed
in the sandbox is done through *AppArmor*, this means that AppArmor must be installed
in the host machine and the `provided profile`_ must be loaded.

.. _provided profile: tutorcodejail/templates/codejail/apps/profiles/docker-edx-sandbox

The plugin provides an init task that runs a privileged container capable of loading
the needed AppArmor profile unto your machine. This is only compatible with a docker
installation. In Kubernetes you must guarantee that each node of your cluster has
AppArmor installed and the profile loaded, for that reason the one time initialization
task that is used in the init is skipped when running on kubernetes.
The plugin provides an init task running a privileged container capable of loading the AppArmor profile onto your machine.
This is only compatible with a docker installation.

The plugins offers the possibility to load the AppArmor profile using a DaemonSet,
assuming the nodes are already running AppArmor. To do so you must set
``CODEJAIL_ENABLE_K8S_DAEMONSET`` to ``True``.
For Kubernetes environments, ensure each node has AppArmor installed and the profile loaded. Optionally,
set ``CODEJAIL_ENABLE_K8S_DAEMONSET`` to True to use a DaemonSet for loading the AppArmor profile,
assuming the nodes are already running AppArmor.

If, at your own discretion, want to run the service without enforcing the AppArmor
profile you can set ``CODEJAIL_ENFORCE_APPARMOR`` to ``False``.
If you choose to run the service without enforcing the AppArmor profile, you can set ``CODEJAIL_ENFORCE_APPARMOR`` to ``False``.

More info about this discussion can be found on `this issue`_.

.. _this issue: https://github.com/eduNEXT/tutor-contrib-codejail/issues/24

Functionality test
------------------

How to know if codejail is working
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The easiest way to test whether codejail is working is to validate it in ``Studio`` with a course
that has loncapa problems.
Testing Functionality
---------------------

This test was performed on the Maple version of Open edx, using the course ``course_codejail_example.tar.gz``
found in the additional resources section.
To verify if Codejail is working, use a course with loncapa problems in ``Studio`` and check for correct execution.
You can import the provided `example course`_ .

Once the course is imported, go to any section and select an exercise (`section example`_), the proper result is:

.. _example course: https://github.com/eduNEXT/tutor-contrib-codejail/blob/main/docs/resources/course_codejail_example.tar.gz
.. _section example: http://studio.local.overhang.io:8001/container/block-v1:edX+DemoX+Demo_Course+type@vertical+block@v-integral1

.. image:: ./docs/resources/Codejailworking.png
:width: 725px
:align: center
:alt: Example when codejail is working

In this case, the section's content will render correctly and will be working as specified in the instructions of the problem.
In this case, the section's content will render correctly and work as specified in the instructions of the problem.

Possible failure case
~~~~~~~~~~~~~~~~~~~~~

In case you forget to run ``tutor local do init --limit codejail`` for apparmor profile, this error in
In case you forget to run ``tutor local do init --limit codejail`` for AppArmor profile, this error in
``Studio`` will arise::

Error formatting HTML for problem:
Expand All @@ -141,15 +146,8 @@ In case you forget to run ``tutor local do init --limit codejail`` for apparmor
:align: center
:alt: Example when codejail is not working

This indicates that the codejail service is not turned on or is not working properly. Be sure to follow the
steps in the usage section so this doesn't happen.

Additional Resources
--------------------

Example course to test the Codejail service: `course_codejail_example.tar.gz`_

.. _course_codejail_example.tar.gz: https://github.com/eduNEXT/tutor-contrib-codejail/blob/main/docs/resources/course_codejail_example.tar.gz
This indicates that the Codejail service is either not turned on or not working properly. Please ensure to follow
the steps outlined in the usage section to prevent this issue.

How to Contribute
-----------------
Expand All @@ -163,4 +161,4 @@ quality, which will make your contribution more likely to be accepted.
License
-------

This software is licensed under the terms of the AGPLv3.
This software is licensed under the terms of the AGPLv3. See the LICENSE file for details.
Loading