Code FREAK Documentation
- 1. Getting started
- 2. Security
- 3. Installation
- 4. Configuration
- 5. Development / Contribution
- 6. License
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.
|Code FREAK is under heavy development. Things might break between updates even if we try to be backwards-compatible.|
1. Getting started
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.
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.
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
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
key.pem files in a directoy
certificates next to your
docker-compose.yml and adjust the configuration
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 ...
TODO explain most simple way to provide a configuration file for the Docker container
For more details refer to the Spring documentation.
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.
Simple authentication has not been implemented yet! It only works in
code-freak.authentication-method: simple # this is the default
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
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.
[code-freak-url] with the public accessible URL of your Code FREAK installation including
The exported public key from the previous step
Deep Linking (Content Selection) URL
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
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://firstname.lastname@example.org
5. Development / Contribution
Code FREAK is licensed under the AGPLv3. For more information see the LICENSE file that comes with the source code.