From 36ec278a7d71e850e51c3874c6e53c8607ca376a Mon Sep 17 00:00:00 2001 From: Sebastian Serth Date: Mon, 26 Aug 2024 01:16:37 +0200 Subject: [PATCH] Update README with Runner Management requirement Further, this commit removes some obsolete and outdated setup instructions, that are now located in the local setup guide. --- README.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 7e6e27ecd..c7546f398 100644 --- a/README.md +++ b/README.md @@ -18,42 +18,35 @@ The programming courses offered on openHPI include practical programming exercis 3. CodeOcean includes unit tests to provide feedback for learners and score their code. A unit test is defined as a program that either runs the learner’s code in a pre-defined way and compares the provided result with an expectation or the unit test parses the student’s source code and matches it against an exercise-defined string. While the code of the unit tests are hidden, learners can run the unit tests at any time and get instant feedback whether they passed or failed. If the unit tests fail the result is shown together with an error message defined by the MOOC instructors. On the one hand, this feedback helps people to help themselves and provides learners with a hint of their mistake. On the other hand, the automated scoring using unit tests is required to indicate progress for the learners. In the context of a MOOC with thousands of active learners, a manual review by the instructors is not feasible and peer-review of source code has not been implemented in CodeOcean so far. 4. In CodeOcean, learners can ask questions about their program directly within the platform and in context of their current program. Usually, MOOC platforms provide a forum to discuss questions. While this concept also works great for source code in general outside of a MOOC (cf. [StackOverflow](https://stackoverflow.com)), it is an additional barrier for novices to summarize their problem externally. To understand the problem, contextual information is generally of help for others to provide the current solution. When using a dedicated forum, learners are required to provide as much information as necessary to reproduce the issue which beginners might find difficult to identify. As a result, they might copy too few or too much information. In addition, early iterations of the Java courses showed that learners did not format their source code appropriate in forum posts (but as plain text), making it difficult to read. With _Request for Comments_, CodeOcean provides a built-in feature to ask a question in the context of an exercise, thus lowering the barriers to get help. CodeOcean presents the learner’s source code and error message together with the question to fellow students and allows them to add a comment specifically to one line of code. Hence, the previously described issue is solved with a dedicated forum. -CodeOcean is mainly used in the context of MOOCs (such as those offered on openHPI and mooc.house) and has been used by more than 60,000 users as of June 2020. CodeOcean is a stand-alone tool implementing the [Learning Tools Interoperability (LTI)](https://www.imsglobal.org/activity/learning-tools-interoperability) standard to be used in various learning scenarios. By offering an LTI interface, it is accessible from MOOC providers as well as other providers, such as the HPI Schul-Cloud. CodeOcean itself cannot be used directly by learners or other users than the MOOCs instructors or administrators. +CodeOcean is mainly used in the context of MOOCs (such as those offered on openHPI) and has been used by more than 120,000 users as of August 2024. CodeOcean is a stand-alone tool implementing the [Learning Tools Interoperability (LTI)](https://www.imsglobal.org/activity/learning-tools-interoperability) standard to be used in various learning scenarios. By offering an LTI interface, it is accessible from MOOC providers as well as other Learning Management Systems (LMS), such as Canvas, Moodle, or dBildungscloud. CodeOcean itself cannot be used directly by learners or other users than the MOOCs instructors or administrators. ## Development Setup Please refer to the [Local Setup Guide](docs/LOCAL_SETUP.md) for more details. Please note that the [Dockerfile](Dockerfile) is intended for production only. -### Mandatory Steps +In order to execute code submissions, a so-called Runner Management is required. The Runner Management is a separate service that is responsible for executing the code submissions in a secure and isolated environment. Historically, CodeOcean used a separate service called [DockerContainerPool](https://github.com/openHPI/dockercontainerpool) for this purpose, which has been replaced by [Poseidon](https://github.com/openHPI/poseidon) many years ago. Poseidon is the recommended setup for CodeOcean. Please refer to the [Poseidon repository](https://github.com/openHPI/poseidon) for more information. -- install the Docker client -- run `bundle install` -- create *config/action_mailer.yml* -- create *config/database.yml* -- customize *config/docker.yml.erb* +The chosen runner management is configured in `config/code_ocean.yml.erb` and likely requires manual setup for development and production use. -Exemplary configuration files are available in the *config* directory. - -In order to execute code submissions using the [DockerContainerPool](https://github.com/openHPI/dockercontainerpool), source code files are written to the file system and are provided to a dedicated Docker container. These files are temporarily written to *Rails.root/tmp/files/*. Please make sure that *workspace_root* in *config/docker.yml.erb* +### DockerContainerPool Setup +When CodeOcean is configured to use the [DockerContainerPool](https://github.com/openHPI/dockercontainerpool) for executions, source code files are first written to the file system and are then mounted to a dedicated Docker container. These files are temporarily written to `Rails.root.join('/tmp/files')`. Please make sure that the `workspace_root` in `config/docker.yml.erb` - corresponds to that directory or to a linked directory if using a remote Docker server. - is always writeable by the user executing the web server (in this case the `codeocean` user): `setfacl -Rdm user:codeocean:rwx /var/www/app/current/tmp/files`. -### Optional Steps -- Use Docker Machine or Vagrant if there is no native support for Docker on your OS -- If you want to use the app without Docker or a Runner management (and hence without code execution), comment the validation `validate :working_docker_image?` in `models/execution_environments.rb`. Otherwise the seed will fail. -- Create seed data by executing `rails db:seed` -- If you already created a configuration for your local installation and want to use vagrant, too, be sure to log into the vagrant instance via ssh and add your database user manually to the database. Afterwards, create, migrate and seed. +### Poseidon Setup +The usage of [Poseidon](https://github.com/openHPI/poseidon) is highly recommended: It is more stable, can be scaled more easily, and executions are stronger isolated from each other. For the Poseidon setup, no shared filesystem is required. Instead, Poseidon provides a RESTful API used by CodeOcean and relies on the container orchestrator [Nomad](https://nomadproject.io) for the actual executions. Please refer to the [Poseidon repository](https://github.com/openHPI/poseidon) for more information, architectural considerations, and setup instructions. ## Production Setup -- We recommend using [Capistrano](https://capistranorb.com/) for deployment. Alternatively, the [Dockerfile](Dockerfile) can be used to build a production-ready Docker image containing the Rails application. +- We recommend using [Capistrano](https://capistranorb.com/) for deployment. Alternatively, the [Dockerfile](Dockerfile) can be used to build a production-ready Docker image containing the Rails application. The devcontainer and Vagrant setup are for local development only. - Once deployed, CodeOcean assumes to run exclusively under a (sub)domain. If you want to use it under a custom subpath, you can specify the desired path using an environment variable: `RAILS_RELATIVE_URL_ROOT=/codeocean`. Please ensure to rebuild all assets and restart the server to apply the new path. - When using [PgBouncer](https://www.pgbouncer.org), please make sure to correctly set the `intervalstyle` to `iso_8601` for the database. Otherwise, the application will not be able to parse timestamps correctly. See [a similar issue here](https://gitlab.com/gitlab-org/gitlab/-/issues/349912) and [our migration](./db/migrate/20221206221333_set_database_interval_style.rb) for more details. +- A Runner management is required for executing code submissions. Please refer to the [Development Setup](#development-setup) section for more details. ## Monitoring - We use a [Prometheus Exporter](https://github.com/discourse/prometheus_exporter) and a [Telegraf Client](https://github.com/jgraichen/telegraf-ruby) - The Telegraf client collects the data from the Prometheus endpoint, adds its own datasets and forwards them to an InfluxDB - The Prometheus Exporter must be started separately **before** running the Rails server via `bundle exec prometheus_exporter` -- The InfluxDB data can be visualized using Grafana, for example. There is also an adapted [dashboard](docs/grafana/prometheus_exporter_grafana_dashboard.json) for this purpose +- The InfluxDB data can be visualized using Grafana, for example. For the data gathered through Prometheus, rhere is also an adapted [dashboard](docs/grafana/prometheus_exporter_grafana_dashboard.json). For request-based data gathered through the Telegraf Client, potential dashboards are shown in the [telegraf-ruby repository](https://github.com/jgraichen/telegraf-ruby/tree/e498bebdadc0c525e45ca18d1fbb1ab735e88c77/examples). ## Additional Note - If you want to change the default port of the underlying rails server, you can use [authbind](https://www.mwells.org/coding/2016/authbind-port-80-443/) to bind it to the regular 80/443 port.