Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
232 lines (184 sloc) 9.37 KB

Code FREAK Documentation

Welcome to the Code FREAK documentation. Code FREAK is an online IDE for educational purposes that allows teachers to create and enroll programming tasks allows students to programm and execute their code without leaving the browser. Submissions can be evaluated automatically by various testing-methods like unit tests or code smell detection.

Warning
Code FREAK is under heavy development. Things might break between updates even if we try to be backwards-compatible.

1. Getting started

If you are new to Code FREAK here are some links that may help you to understand the basic concepts of the system:

2. Security

We utilize Linux containers based on Docker which allow a good logical isolation (separate process-set, resource-limits, …). It should be very difficult to escape from the containers and do harm to the underlying host-system but we do not guarantee that it is impossible. This is why we recommend to run a dedicated Docker daemon only for Code FREAK that does nothing else except hosting the IDE instances and running untrusted code. Additionally you should not run the Code FREAK application and its sidekick Docker daemon on the same host for similar reasons: If someone manages to escape the IDE containers they could hijack the backend application and steal sensitive information. Even if someone does not accomplishes to break out of the container they could spin up so many containers that all host system resources are exhausted.

3. Installation

There are various methods to run the application in production. We only support the Docker/docker-compose setup. If you plan to run the application directly on a host-system you should know what you are doing. If you are looking for a development setup please take a look at the Development / Contribution section.

3.1. Prerequisites

For the backend application:

  • A Docker host/daemon

  • About 1-2GB RAM

For the dedicated docker daemon:

  • Separated Docker daemon that does not run on the same host as the backend application

  • Lots of memory. You should plan 3-4GB RAM per concurrent user (depending on the programming language). We are working on reducing the RAM usage.

  • About CPU 1 Core / concurrent 10 users

3.2. Preparing the Docker daemon

Docker allows to connect via HTTP/TLS to the integrated API. This requires to set up a PKI for certificate-management. There is an extensive documentation on how to do this in the official Docker docs. Please follow this article carefully. As the result you should have a ca.pem, cert.pem and key.pem file that can be used on your backend application host.

3.3. Set up using Docker Compose

We have included a sample docker-compose.yml in the main repository. This should work fine out-of-the-box but uses a Docker-in-Docker container which is not suited for development. Please remove the docker service and adjust the environment-variables of the app service that it points to your dedicated Docker host. Place the ca.pem, cert.pem and key.pem files in a directoy certificates next to your docker-compose.yml and adjust the configuration accordingly:

version: "3"
services:
  app:
    # ... SNIP ...
    volumes:
      - "./certificates:/var/code-freak/certs"
    environment:
      DOCKER_HOST: "http://docker-host.at-your-company.domain.com:2376"
      DOCKER_CERT_PATH: "/var/code-freak/certs"
      # ... SNIP ...

4. Configuration

TODO explain most simple way to provide a configuration file for the Docker container

For more details refer to the Spring documentation.

4.1. Authentication

Code FREAK provides multiple ways to authenticate users. You can choose one of the following methods to integrate the application with your existing infrastructure.

4.1.1. Simple Authentication

Simple authentication means that users are managed by Code FREAK itself. Accounts are created by administrators and saved to the database.

Warning
Simple authentication has not been implemented yet! It only works in dev mode with preconfigured users. See #122 for progress.
code-freak.authentication-method: simple # this is the default

4.1.2. LDAP

Code FREAK can connect to an LDAP server and use it for authentication. A minimal configuration requires the URL of the server and a mapping from LDAP groups to Code FREAK roles.

As an example, you can find an LDAP test server here. It can be used with the following configuration.

code-freak:
  authentication-method: ldap
  ldap:
    url: ldap://127.0.0.1:389
    root-dn: dc=planetexpress,dc=com
    group-search-base: ou=people
    role-mappings.admin_staff: admin
    role-mappings.ship_crew: student
    #active-directory: true (set this if you are using an Active Directory server)

4.2. LTI 1.3 Integration

Code FREAK supports integration with Learn Management Systems (LMS) like Moodle or Canvas via the LTI 1.3 standard. Before you begin make sure your LMS supports the LTI 1.3 standard. LTI 1.0 and 2.0 are NOT supported! You need the following information from your LMS:

  • LTI authentication URL

  • LTI/OAuth 2.0 token URL

  • URL to receive the JWK-set of the LMS

  • A client ID (should be generated by your LMS when registering an external tool)

In addition you need to create an RSA keypair and put them into a Java key store. This is required to cryptographically sign the messages send between Code FREAK and the LMS.

4.2.1. Generate the RSA key pair and Java key store

The following instructions will show you how to generate an RSA key pair with the Java keytool and how to extract the public key (often needed for you LMS) with openssl. You will need to have openssl and the JDK’s keytool installed. Please consult a search engine of your choice how to do this for your platform.

Generate the keystore:

This will create a file called cf-keys.pkcs12 with a public/private key pair.

$ keytool -genkey \
  -keystore cf-keys.p12 \
  -storepass "supersecurepassword123" \
  -keyalg RSA \
  -alias codefreak \
  -validity 10950
Export public key in PEM format:

This will extract the public key (without certificate information) from the pkcs12 file you just created. You may need this information when registering Code FREAK as external tool in your CMS.

$ openssl pkcs12 -in cf-keys.pkcs12 -nokeys | openssl x509 -pubkey -noout
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQE ...

4.2.2. Register Code FREAK as LTI Tool

Please check the manual of your LMS how to register external LTI 1.3 Tools. If required please use the following information.

Please replace [code-freak-url] with the public accessible URL of your Code FREAK installation including http(s)://…​

Attribute Value

Tool Name

Code FREAK

Tool URL

[code-freak-url]

LTI Version

1.3

Public key

The exported public key from the previous step

Login URL

[code-freak-url]/lti/login

Redirect URLs

[code-freak-url]/lti/launch

Deep Linking (Content Selection) URL

[code-freak-url]/lti/select-content

Icon URL

[code-freak-url]/images/lti-code-icon.png

The LMS should generate a Client ID for you. Please write it down for the next step.

4.2.3. Configuring Code FREAK for LTI

Please put the key store file in a location where the Code FREAK process can read it. If you are running Code FREAK with Docker you may have to mount the generated key store as volume inside the container.

Adjust the configuration with all the information you received from your LMS. The following is an example that should work with Moodle 3.7 and later:

code-freak:
  lti:
    enabled: true
    key-store: file:/path/to/your/keystore/cf-keys.p12
    key-store-type: PKCS12
    # for pkcs12 key stores the store password and entry pin are always the same
    key-store-password: supersecurepassword123
    providers:
      - name: Some human-readable name
        issuer: "https://lms.example.org"
        client-id: client-id-from-your-lms
        auth-url: "https://lms.example.org/mod/lti/auth.php"
        token-url: "https://lms.example.org/mod/lti/token.php"
        jwk-url: "https://lms.example.org/mod/lti/certs.php"
        key-store-entry-name: codefreak
        key-store-entry-pin: supersecurepassword123

4.3. Git import

You can allow your students to import their source code from a remote Git repository. Currently, this is possible only via a shared SSH key that has access to all repositories on the Git server. Some Git servers allow this by using so-called "deplyoment keys". You can configure multiple hosts but only one SSH key per host. Students have to use the clone URL starting with ssh:// when importing from the remote repository. Import via HTTP is not possible currently.

code-freak:
    git-import:
      enabled: true
      remotes:
      - host: git.example.org
        ssh-key: /path/to/ssh/id_rsa
        ssh-key-pass: securepassword123
        ssh-base-url: ssh://git@git.example.org

5. Development / Contribution

TODO

6. License

Code FREAK is licensed under the AGPLv3. For more information see the LICENSE file that comes with the source code.

You can’t perform that action at this time.