Codejail plugin for `Tutor`_
============================
Tutor plugin that configures and runs a `Codejail Service`_ using a REST API. `Codejail`_ allows for the
secure execution of untrusted code within sandboxes, providing a safe environment for running potentially dangerous code.
.. _Tutor: https://docs.tutor.overhang.io
.. _Codejail Service: https://github.com/eduNEXT/codejailservice
.. _Codejail: https://github.com/openedx/codejail
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/tutor-contrib-codejail@v18.0.0
Usage
-----
Enable the plugin with:
.. code-block:: bash
tutor plugins enable codejail
Run the initialization jobs to install the required AppArmor profile on your host:
.. code-block:: bash
tutor config save
tutor local do init --limit codejail
Finally, the platform can be run as usual:
.. code-block:: bash
tutor local launch
**Please remember:** If the host is rebooted, the AppArmor profile needs to be reloaded.
Configuration
-------------
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:{{__version__}}``)
- ``CODEJAIL_ENFORCE_APPARMOR`` (default: ``True``)
- ``CODEJAIL_ENABLE_K8S_DAEMONSET`` (default: ``False``)
- ``CODEJAIL_SKIP_INIT`` (default: ``False``)
- ``CODEJAIL_SANDBOX_PYTHON_VERSION`` (default: ``3.8.6``)
- ``CODEJAIL_EXTRA_PIP_REQUIREMENTS`` (optional) A list of pip requirements to add to your sandbox.
- ``CODEJAIL_SERVICE_VERSION`` (default: ``release/redwood.1``),
- ``CODEJAIL_SERVICE_REPOSITORY`` (default ``https://github.com/edunext/codejailservice.git```)
.. code-block:: yaml
CODEJAIL_EXTRA_PIP_REQUIREMENTS:
- pybryt
Custom Image
~~~~~~~~~~~~
In most cases, you can work with the provided docker image for the release. However, you will need to re-build the docker image when:
. Additional requirements are included in the sandbox via ``CODEJAIL_EXTRA_PIP_REQUIREMENTS``.
- A different version of Python is set for the sandbox environment via ``CODEJAIL_SANDBOX_PYTHON_VERSION``.
- The custom version of edx-platform that changes the contents of requirements/edx-sandbox.
Create a new image running:
.. code-block:: bash
# Add the tutor configuration with the custom value
tutor config save \
--set 'CODEJAIL_EXTRA_PIP_REQUIREMENTS=["pybryt"]'
# Build the image
tutor images build codejail
Compatibility
-------------
+------------------+---------------+
| Open edX Release | Tutor Version |
+==================+===============+
| Lilac | >= 12.x |
+------------------+---------------+
| Maple | >= 13.x |
+------------------+---------------+
| Nutmeg | >= 14.x |
+------------------+---------------+
| Olive | >= 15.x |
+------------------+---------------+
| Palm | >= 16.x |
+------------------+---------------+
| Quince | >= 17.x |
+------------------+---------------+
| Redwood | >= 18.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``. 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 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 running a privileged container capable of loading the AppArmor profile onto your machine.
This is only compatible with a docker installation.
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 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
Testing Functionality
---------------------
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 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
``Studio`` will arise::
Error formatting HTML for the problem:
cannot create LoncapaProblem block-v1:edX+DemoX+Demo_Course+type@problem+block@integral1: Error while
executing script code: Codejail API Service is unavailable. Please try again in a few minutes.
.. image:: ./docs/resources/Codejailfail.png
:width: 750px
:align: center
:alt: Example when codejail is not working
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
-----------------
Contributions are welcome! See our `CONTRIBUTING`_ file for more
information – it also contains guidelines for how to maintain high code
quality, which will make your contribution more likely to be accepted.
.. _CONTRIBUTING: https://github.com/eduNEXT/tutor-contrib-codejail/blob/main/CONTRIBUTING.rst
License
-------
This software is licensed under the terms of the AGPLv3. See the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/github/tutor-contrib-codejail",
"name": "tutor-contrib-codejail",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "eduNEXT",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/39/80/7ac96ebe15a04b3da3a3f07e0e5ab69f5dc58c353514150b884de5f61422/tutor_contrib_codejail-19.1.1.tar.gz",
"platform": null,
"description": "Codejail plugin for `Tutor`_\n============================\n\nTutor plugin that configures and runs a `Codejail Service`_ using a REST API. `Codejail`_ allows for the\nsecure execution of untrusted code within sandboxes, providing a safe environment for running potentially dangerous code.\n\n.. _Tutor: https://docs.tutor.overhang.io\n.. _Codejail Service: https://github.com/eduNEXT/codejailservice\n.. _Codejail: https://github.com/openedx/codejail\n\nInstallation\n------------\n\nTo install the latest version run:\n\n.. code-block:: bash\n\n pip install git+https://github.com/edunext/tutor-contrib-codejail\n\nYou can install a specific version by adding the tag, branch, or commit:\n\n.. code-block:: bash\n\n pip install git+https://github.com/edunext/tutor-contrib-codejail@v18.0.0\n\nUsage\n-----\nEnable the plugin with:\n\n.. code-block:: bash\n\n tutor plugins enable codejail\n\nRun the initialization jobs to install the required AppArmor profile on your host:\n\n.. code-block:: bash\n\n tutor config save\n tutor local do init --limit codejail\n\nFinally, the platform can be run as usual:\n\n.. code-block:: bash\n\n tutor local launch\n\n**Please remember:** If the host is rebooted, the AppArmor profile needs to be reloaded.\n\nConfiguration\n-------------\n\nTo customize the configuration, update the following settings in Tutor:\n\n- ``CODEJAIL_APPARMOR_DOCKER_IMAGE``: (default: ``docker.io/ednxops/codejail_apparmor_loader:latest``)\n- ``CODEJAIL_DOCKER_IMAGE``: (default: ``docker.io/ednxops/codejailservice:{{__version__}}``)\n- ``CODEJAIL_ENFORCE_APPARMOR`` (default: ``True``)\n- ``CODEJAIL_ENABLE_K8S_DAEMONSET`` (default: ``False``)\n- ``CODEJAIL_SKIP_INIT`` (default: ``False``)\n- ``CODEJAIL_SANDBOX_PYTHON_VERSION`` (default: ``3.8.6``)\n- ``CODEJAIL_EXTRA_PIP_REQUIREMENTS`` (optional) A list of pip requirements to add to your sandbox.\n- ``CODEJAIL_SERVICE_VERSION`` (default: ``release/redwood.1``),\n- ``CODEJAIL_SERVICE_REPOSITORY`` (default ``https://github.com/edunext/codejailservice.git```)\n\n.. code-block:: yaml\n\n CODEJAIL_EXTRA_PIP_REQUIREMENTS:\n - pybryt\n\n\nCustom Image\n~~~~~~~~~~~~\n\nIn most cases, you can work with the provided docker image for the release. However, you will need to re-build the docker image when:\n\n. Additional requirements are included in the sandbox via ``CODEJAIL_EXTRA_PIP_REQUIREMENTS``.\n- A different version of Python is set for the sandbox environment via ``CODEJAIL_SANDBOX_PYTHON_VERSION``.\n- The custom version of edx-platform that changes the contents of requirements/edx-sandbox.\n\nCreate a new image running:\n\n.. code-block:: bash\n\n # Add the tutor configuration with the custom value\n tutor config save \\\n --set 'CODEJAIL_EXTRA_PIP_REQUIREMENTS=[\"pybryt\"]'\n\n # Build the image\n tutor images build codejail\n\n\nCompatibility\n-------------\n\n+------------------+---------------+\n| Open edX Release | Tutor Version |\n+==================+===============+\n| Lilac | >= 12.x |\n+------------------+---------------+\n| Maple | >= 13.x |\n+------------------+---------------+\n| Nutmeg | >= 14.x |\n+------------------+---------------+\n| Olive | >= 15.x |\n+------------------+---------------+\n| Palm | >= 16.x |\n+------------------+---------------+\n| Quince | >= 17.x |\n+------------------+---------------+\n| Redwood | >= 18.x |\n+------------------+---------------+\n\n**NOTE**: For the Open edX version of the Lilac release, the changes required for the Codejail service to interact with ``edx-platform`` are\nnot included in ``open-release/lilac.master``. To use the service with the changes, please review `this PR`_.\n\n.. _this PR: https://github.com/openedx/edx-platform/pull/27795\n\nKubernetes Support\n------------------\n\nThe CodeJail service provides a sandbox to run arbitrary code. Security enforcement\nin the sandbox is done through *AppArmor*, this means that AppArmor must be installed\nin the host machine and the `provided profile`_ must be loaded.\n\n.. _provided profile: tutorcodejail/templates/codejail/apps/profiles/docker-edx-sandbox\n\nThe plugin provides an init task running a privileged container capable of loading the AppArmor profile onto your machine.\nThis is only compatible with a docker installation.\n\nFor Kubernetes environments, ensure each node has AppArmor installed and the profile loaded. Optionally,\nset ``CODEJAIL_ENABLE_K8S_DAEMONSET`` to True to use a DaemonSet for loading the AppArmor profile,\nassuming the nodes are already running AppArmor.\n\nIf you choose to run the service without enforcing the AppArmor profile, you can set ``CODEJAIL_ENFORCE_APPARMOR`` to ``False``.\n\nMore info about this discussion can be found on `this issue`_.\n\n.. _this issue: https://github.com/eduNEXT/tutor-contrib-codejail/issues/24\n\nTesting Functionality\n---------------------\n\nTo verify if Codejail is working, use a course with loncapa problems in ``Studio`` and check for correct execution.\nYou can import the provided `example course`_.\n\nOnce the course is imported, go to any section and select an exercise (`section example`_), the proper result is:\n\n.. _example course: https://github.com/eduNEXT/tutor-contrib-codejail/blob/main/docs/resources/course_codejail_example.tar.gz\n.. _section example: http://studio.local.overhang.io:8001/container/block-v1:edX+DemoX+Demo_Course+type@vertical+block@v-integral1\n\n.. image:: ./docs/resources/Codejailworking.png\n :width: 725px\n :align: center\n :alt: Example when codejail is working\n\nIn this case, the section's content will render correctly and work as specified in the instructions of the problem.\n\nPossible failure case\n~~~~~~~~~~~~~~~~~~~~~\n\nIn case you forget to run ``tutor local do init --limit codejail`` for AppArmor profile, this error in\n``Studio`` will arise::\n\n Error formatting HTML for the problem:\n cannot create LoncapaProblem block-v1:edX+DemoX+Demo_Course+type@problem+block@integral1: Error while\n executing script code: Codejail API Service is unavailable. Please try again in a few minutes.\n\n.. image:: ./docs/resources/Codejailfail.png\n :width: 750px\n :align: center\n :alt: Example when codejail is not working\n\nThis indicates that the Codejail service is either not turned on or not working properly. Please ensure to follow\nthe steps outlined in the usage section to prevent this issue.\n\nHow to Contribute\n-----------------\n\nContributions are welcome! See our `CONTRIBUTING`_ file for more\ninformation \u2013 it also contains guidelines for how to maintain high code\nquality, which will make your contribution more likely to be accepted.\n\n.. _CONTRIBUTING: https://github.com/eduNEXT/tutor-contrib-codejail/blob/main/CONTRIBUTING.rst\n\nLicense\n-------\n\nThis software is licensed under the terms of the AGPLv3. See the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "AGPLv3",
"summary": "Codejail plugin for Tutor",
"version": "19.1.1",
"project_urls": {
"Code": "https://github.com/edunext/tutor-contrib-codejail",
"Homepage": "https://github.com/github/tutor-contrib-codejail",
"Issue tracker": "https://github.com/edunext/tutor-contrib-codejail/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "712f505e77cbdcc0d4d52ec834e9e98fe62aa775a8029e32f77d101a7bfbf10c",
"md5": "e1071e1424893d408ed7c0c2c7b1916b",
"sha256": "4c4d6da31a5a404376d665d742e39b248f56f8baeb9f7674c42bcf405f084059"
},
"downloads": -1,
"filename": "tutor_contrib_codejail-19.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "e1071e1424893d408ed7c0c2c7b1916b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 28795,
"upload_time": "2025-04-07T19:12:48",
"upload_time_iso_8601": "2025-04-07T19:12:48.180819Z",
"url": "https://files.pythonhosted.org/packages/71/2f/505e77cbdcc0d4d52ec834e9e98fe62aa775a8029e32f77d101a7bfbf10c/tutor_contrib_codejail-19.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "39807ac96ebe15a04b3da3a3f07e0e5ab69f5dc58c353514150b884de5f61422",
"md5": "26cb15cf4a300aeea86bd9de44452190",
"sha256": "538e3f02bd55a1f1bd5b7c8c2cf34ddc5fcd4ebdd8024558f65fc9d49f88eac5"
},
"downloads": -1,
"filename": "tutor_contrib_codejail-19.1.1.tar.gz",
"has_sig": false,
"md5_digest": "26cb15cf4a300aeea86bd9de44452190",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23822,
"upload_time": "2025-04-07T19:12:49",
"upload_time_iso_8601": "2025-04-07T19:12:49.097847Z",
"url": "https://files.pythonhosted.org/packages/39/80/7ac96ebe15a04b3da3a3f07e0e5ab69f5dc58c353514150b884de5f61422/tutor_contrib_codejail-19.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-07 19:12:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "github",
"github_project": "tutor-contrib-codejail",
"github_not_found": true,
"lcname": "tutor-contrib-codejail"
}
JSON
