OpenSubmit consists of two parts: The web application and the executor daemon. The web application provides the user interface for students and teachers, while the executor daemons evaluate student code with according test scripts.
If you just want to play around, use our demo installation.
Full-stack installation with Terraform¶
Full-stack installation with Docker Compose¶
We offer a Docker Compose script for deploying a complete OpenSubmit environment (web frontend, test machine, database) on a single machine running a normal Docker installation. For such an installation:
- Download the compose file on the machine.
docker-compose upto download, configure and start the OpenSubmit Docker containers and a separate database container.
- Got to
http://localhost:8000and use one of the configured authentication methods.
Single installation of the web application¶
For the OpenSubmit web application alone, there are two options to run it:
The latest official release of the OpenSubmit web application is available as Docker image. It expects a couple of environment variables to be set, which you can easily determine from the compose file.
When you want to run the OpenSubmit web application without Docker, you need to follow these steps:
- Prepare a Python 3 web hosting environment.
- Debian / Ubuntu:
apt-get install libapache2-mod-wsgi-py3 apache2 sqlite python3.
- Debian / Ubuntu:
pip install opensubmit-webas root or in a virtualenv environment. If you get error messages about unresolved dependencies, try running
pip install -U opensubmit-web. PIP should come as part of your Python installation.
opensubmit-web configcreateto create an OpenSubmit configuration file. Check the configuration section for details.
opensubmit-web configtestto check your configuration.
opensubmit-web apachecreateto generate a default Apache 2.4 configuration for mod_wsgi, which is stored in
/etc/opensubmit/apache24.config. You can include this file in some virtual host configuration.
- Restart your web server.
- Got to the OpenSubmit start page and use your configured authentication method.
opensubmit-web makeadmin <email>to make the created user an administrator in the system.
Updating an existing manual installation is easy:
pip install --upgrade opensubmit-webas root or in the virtualenv environment.
opensubmit-web configtestto perform neccessary database updates.
- Restart your web server.
Single installation of a test machine¶
Test machines are used to run the validation scripts (see Automated testing of submissions) for student submission. Pending validation jobs are fetched from the OpenSubmit web server in regular intervals and executed on a test machine.
The creator of an assignment can chose which test machines are used for the validation. This enables a flexible setup with dedicated test machines for special assignments, e.g. GPU programming.
There are two options for installation:
The latest official release of the OpenSubmit executor application is available as Docker image. It expects a single environment variable to be set, which you can easily determine from the compose file.
When you want to run the OpenSubmit executor daemon without Docker, you need to follow these steps:
Both the validator library and the job fetching is implemented in a Python package called
opensubmit-exec (the executor). It runs with Python 3.4 or newer versions. For an installation, you need to follow these steps:
- Choose a dedicated machine beside the web server. It will compile (and run) the student submissions.
- Think again. IT WILL RUN THE STUDENT SUBMISSIONS. Perform all neccessary security precautions, such as network isolation and limited local rights.
- Install Python >= 3.4 on the machine. e.g. through
sudo apt-get install python3 python3-pip.
pip3 install opensubmit-execas root or in a virtualenv environment. If you get error messages about unresolved dependencies, try running
pip install -U opensubmit-exec. PIP should come as part of your Python installation.
- Create an initial configuration as described in the configuration section.
opensubmit-exec configtestto check your configuration.
- Add a call to
opensubmit-exec runto cron, so that it regulary asks the web server for fresh work. We have good experiences with a 30s interval. You can also do it manually for testing purposes.
Smart students may try to connect to machines under their control in their code, mainly for copying validation scripts. An easy prevention mechanism is the restriction of your test machine network routing so that it can talk to the web server only.
The fetching of validations is protected by a shared secret between the web application and the executor installations. Check both the
settings.ini on the web server and
executor.ini on the test machines.
Updating an existing manual executor installation consists of the following steps:
pip install --upgrade opensubmit-execas root or in a virtualenv environment.
opensubmit-exec configtestto check the configuration for compatibility.
Configuration of the web application¶
The web application searches for a configuration file in
/etc/opensubmit/settings.ini. This file should be initially created by calling
opensubmit-web configcreate. The command allows to pre-define specific configuration options via command-line, or environment variables, and creates an according config file.
The Docker images run
opensubmit-web configcreate on every startup. Since this command considers environment variables, you can easily set all your options in the normal Docker way.
The following table shows all supported configuration options:
|Command-line option||Environment variable||Description|
|–debug||OPENSUBMIT_DEBUG||Enable debug mode, not for production systems|
|–server_url||OPENSUBMIT_SERVER_URL||The main URL of the OpenSubmit installation, including sub-directories|
|–server_mediaroot||OPENSUBMIT_SERVER_MEDIAROOT||Storage path for uploadeded files|
|–server_hostaliases||OPENSUBMIT_SERVER_HOSTALIASES||Comma-separated list of alternative host names for the web server|
|–server_logfile||OPENSUBMIT_SERVER_LOGFILE||Log file for the OpenSubmit application|
|–server_timezone||OPENSUBMIT_SERVER_TIMEZONE||Time zone for all dates and deadlines|
|–database_name||OPENSUBMIT_DATABASE_NAME||Name of the database (file)|
|–database_engine||OPENSUBMIT_DATABASE_ENGINE||Datababase engine being used|
|–database_user||OPENSUBMIT_DATABASE_USER||The user name for accessing the database. Not needed for SQLite|
|–database_password||OPENSUBMIT_DATABASE_PASSWORD||The user password for accessing the database. Not needed for SQLite|
|–database_host||OPENSUBMIT_DATABASE_HOST||The host name for accessing the database. Not needed for SQLite|
|–database_port||OPENSUBMIT_DATABASE_PORT||The port number for accessing the database. Not needed for SQLite|
|–login_google_oauth_key||OPENSUBMIT_LOGIN_GOOGLE_OAUTH_KEY||Google OAuth client key|
|–login_google_oauth_secret||OPENSUBMIT_LOGIN_GOOGLE_OAUTH_SECRET||Google OAuth client secret|
|–login_twitter_oauth_key||OPENSUBMIT_LOGIN_TWITTER_OAUTH_KEY||Twitter OAuth client key|
|–login_twitter_oauth_secret||OPENSUBMIT_LOGIN_TWITTER_OAUTH_SECRET||Twitter OAuth client secret|
|–login_github_oauth_key||OPENSUBMIT_LOGIN_GITHUB_OAUTH_KEY||GitHub OAuth client key|
|–login_github_oauth_secret||OPENSUBMIT_LOGIN_GITHUB_OAUTH_SECRET||GitHub OAuth client secret|
|–login_openid_description||OPENSUBMIT_LOGIN_OPENID_DESCRIPTION||Title of the OpenID login button|
|–login_openid_provider||OPENSUBMIT_LOGIN_OPENID_PROVIDER||URL of the OpenID provider|
|–login_oidc_description||OPENSUBMIT_LOGIN_OIDC_DESCRIPTION||Title of the OpenID Connect login button|
|–login_oidc_endpoint||OPENSUBMIT_LOGIN_OIDC_ENDPOINT||URL of the OpenID Connect endpoint|
|–login_oidc_client_id||OPENSUBMIT_LOGIN_OIDC_CLIENT_ID||OpenID Connect client id|
|–login_oidc_client_secret||OPENSUBMIT_LOGIN_OIDC_CLIENT_SECRET||OpenID Connect client secret|
|–login_shib_description||OPENSUBMIT_LOGIN_SHIB_DESCRIPTION||Title of the Shibboleth login button|
|–login_demo||OPENSUBMIT_LOGIN_DEMO||Offer demo login options|
|–admin_impress_page||OPENSUBMIT_IMPRESS_PAGE||Link to alternative impress page|
opensubmit-web configcreate -h for more details.
- Option 1: Your configuration file defines name, address, and email of an administrator. The according options for
OpenSubmit supports different authentication methods, as described in the following sections. It does not support password-based logins - authentication is always supposed to be handled by some third-party service.
If you need another authentication method for your institution, please open an according issue.
Authentication methods show up on the front page when the according settings are not empty. You can therefore disable any of the mechanisms by commenting them out in settings.ini.
Login with OpenID Connect¶
If you want to allow users to login with OpenID Connect (OIDC), you need to configure the following settings:
LOGIN_OIDC_DESCRIPTION: <visible button title>
LOGIN_OIDC_ENDPOINT: <OpenID connect endpoint URL>
LOGIN_OIDC_CLIENT_ID: <OpenID client ID>
LOGIN_OIDC_CLIENT_SECRET: <OpenID client secret>
Login with classical OpenID¶
If you want to allow users to login with classical OpenID, you need to configure the following settings:
LOGIN_DESCRIPTION: <visible button title>
OPENID_PROVIDER: <provider URL>
The standard OpenSubmit installation already contains an example setting for using StackExchange as authentication provider. Please note that classical OpenID is considered as being deprecated. We recommend to use OpenID Connect instead.
Login with Shibboleth¶
If you want to allow users to login with Shibboleth, you need to configure the following settings:
LOGIN_SHIB_DESCRIPTION: <visible button title>
You also need a fully working installation of the Apache 2.4 mod_shib module. The authentication module of OpenSubmit assumes that, as result of the work of mod_shib, the following environment variables are given:
REMOTE_USER: The user name of the authenticated user.
HTTP_SHIB_ORGPERSON_EMAILADDRESS: The email address of the authenticated user.
HTTP_SHIB_INETORGPERSON_GIVENNAME: The first name of the authenticated user.
HTTP_SHIB_PERSON_SURNAME: The last name of the authenticated user.
Note: If you are using Apache 2.4 with mod_wsgi, make sure to set
WSGIPassAuthorization On. Otherwise, these environment variables may not pass through.
Login with Google account¶
If you want to allow users to login with an Google account, you need to configure the following settings:
LOGIN_GOOGLE_OAUTH_KEY: <OAuth key>
LOGIN_GOOGLE_OAUTH_SECRET: <OAuth secret>
A new pair can be created in the Google API Console. The authorized forwarding URL should be
<base url of your installation>/complete/google-oauth2/.
You also need to activate the Google+ API, so that OpenSubmit is able to fetch basic user information from Google.
Login with Twitter account¶
If you want to allow users to login with an Twitter account, you need to configure the following settings:
LOGIN_TWITTER_OAUTH_KEY: <OAuth key>
LOGIN_TWITTER_OAUTH_SECRET: <OAuth secret>
A new key / secret pair can be created in the Twitter Application Management. The authorized forwarding URL should be
<base url of your installation>/complete/twitter/. We recommend to modify the application access to Read only, and to allow access to the email addresses.
Login with GitHub account¶
If you want to allow users to login with an GitHub account, you need to configure the following settings:
LOGIN_GITHUB_OAUTH_KEY: <OAuth key>
LOGIN_GITHUB_OAUTH_SECRET: <OAuth secret>
A new key / secret pair can be created in the OAuth application registration. The authorized forwarding URL should be
<base url of your installation>/complete/github/.
Configuration of the executor¶
The executor searches for a configuration file in
/etc/opensubmit/executor.ini. This file should be initially created by calling
opensubmit-exec configcreate. This management command allows to pre-define specific configuration options via command-line or environment variables, and creates an according config file. Check
opensubmit-exec configcreate -h for details.
One of the core concepts of OpenSubmit is that users register themselves by using an external authentication provider (see Authentication methods).
Based on this, there are different groups such a registered user can belong to:
- Students (default): Users who cannot access the teacher backend.
- Student Tutors: Users with limited rights in the teacher backend.
- Course Owners: Users with advanced rights in the teacher backend.
- Administrators: Users will unrestricted rights.
The following table summarized the default permissions for each of the user groups.
|Permission||Students||Student Tutors||Course Owners||Administrators|
||No||Yes ||Yes ||Yes |
||No||Yes ||Yes ||Yes |
||No||No||Yes ||Yes |
|||(1, 2) Only for courses where the user was chosen as tutor.|
|||(1, 2, 3, 4, 5, 6) Only for courses where the user was chosen as tutor or course owner.|
Administrators can create custom user groups and permissions. Normally this should be avoided, since some permissions have a non-obvious impact on the usage of the teacher backend.
Assigning users to groups¶
There are two ways to assign users to user groups, assuming that they logged-in once for registration:
- In the teacher backend, as administrator (see Authentication methods).
- With the
The first option is the web-based configuration of user groups, which is only available for administrators. Click on Manage users and mark all user accounts to be modified. After that, choose an according action in the lower left corner of the screen.
The second option is the
opensubmit-web command-line tool that is available on the web server. Calling it without arguments shows the different options to assign users to user groups.
Since OpenSubmit users always register themselves in the platform (see Authentication methods), it can happen that the same physical person creates multiple accounts through different authentication providers. The main reason for that is a non-matching or missing email address being provided by the authentication provider.
Administrators can merge users in the teacher backend. Click on Manage users, mark all user accounts to be merged, and choose the according action in the lower left corner. The nect screen shows you the intended merging activity and allows to chose the “primary” account by flipping roles. The non-primary account is deleted as part of the merging activity.