Getting Started

This guide is only for developers! If you would like to deploy Code FREAK to your servers please check out the admin installation guide.

1. Programming Languages and Frameworks

Code FREAK uses Spring/Kotlin for its backend code and React/Typescript for the frontend. Frontend and backend communicate over a GraphQL API. Because Code FREAK makes heavy use of containers some basic Docker knowledge can be useful.

Before you start developing, please install the following tools/software on your computer:

2. Directory Structure

At its root the Code FREAK code base is a Gradle project. All backend code resides inside the /src directory. The frontend code lives inside the /client directory as its own Gradle module. Beside frontend and backend code there is only the /docs directory were you will find the source for this documentation.

3. Development Setup Steps

We recommend using an IDE that can handle both Kotlin and Typescript (e.g. IntellJ Ultimate).

You need Docker to run and build Code FREAK! Please install the official Docker (Desktop) distribution for your operating system before you run the steps below.
Currently, you cannot use Docker Desktop on Windows because of a problem with our underlying Docker library. On Windows please use the Vagrant virtual machine as described in section Docker.
  1. Obtain the source code of Code FREAK from GitHub: git clone https://github.com/codefreak/codefreak.git

  2. Generate the GraphQL schema: ./gradlew client:generate (this will also install all backend and frontend dependencies)

  3. Start the backend with ./gradlew bootRun. The task may stop at 88% but if you see a log line like "Code FREAK instance id: default" the backend is running! You can check this if you point your browser to http://localhost:8080 and see a 404 error page.

  4. Start the frontend inside the client directory with npm start (initial compilation may take some time)

The frontend should open automatically. If it does not please open http://localhost:3000 in you browser. For default credentials see Authentication. Please be aware that all data is stored in an in-memory database by default that does not survive backend restarts! See the configuration below to improve the default settings.

4. Building Code FREAK

Build Code FREAK by using ./gradlew jibDockerBuild. This will generate the Docker image cfreak/codefreak on your local machine.

5. Configuration

Create the file src/main/resources/application-dev.yml. For documentation on how to configure the server see application.yml in the same directory.

5.1. Database

You can either use the embedded HSQL storage or a PostgreSQL database. Data from the HSQL database will get lost when the application shuts down. For Postgres create at least a dedicated database and adjust the configuration accordingly:

spring:
  datasource:
    url: "jdbc:postgresql://localhost:5432/codefreak"
    username: postgres
    password: portgres
    driver-class-name: org.postgresql.Driver
  jpa:
    database-platform: org.hibernate.dialect.PostgreSQLDialect

5.2. Docker

For many parts of the application we need connection to a (dedicated) Docker daemon. By default, we use the default socket for your platform. If you are on Linux please follow the installation guidelines for your distribution. For Windows and MacOS we recommend using the virtual machine setup we ship with the Code FREAK source code. Please install Virtual Box and Vagrant on Windows/MacOS. After installing both you create the virtual machine by running vagrant up in the root directory containing the file Vagrantfile. The initial setup may take some time. When the machine is running (can be confirmed by running vagrant status) you can update the Code FREAK configuration to use the Docker daemon of the virtual machine:

src/main/resources/application-dev.yml
codefreak:
  docker:
    host: "http://127.0.0.1:2375"
  reverse-proxy:
    type: traefik
    url: "http://localhost:8081"

The Code FREAK backend and frontend can still be run locally from your Windows or MacOS machine! The virtual machine will only be used by Code FREAK for Docker related jobs. For running docker CLI commands (like docker ps) you can connect to the virtual machines terminal with vagrant ssh. In the established connection all docker commands will point the the VM’s Docker daemon.

6. Run the application

If you use IntelliJ simply start the CodeFreakApplication Spring Boot application. For Gradle run the command ./gradlew bootRun. The application is started at http://localhost:8080.

7. Authentication

The following sample users are pre-configured for development.

Table 1. Sample Users
Username Password Role

admin

123

ADMIN

teacher

123

TEACHER

student

123

STUDENT

8. Running tests

8.1. Unit tests

To run the unit tests you need a working Docker connection. It is also possible to use the Vagrant machine for Testing:

$ ./gradlew test          # for testing with local Docker daemon
$ ./gradlew vagrantTest   # for testing with Vagrant Docker daemon

The unit tests for the backend are run with JUnit 4. The test files are found in the src/test/kotlin/org/codefreak/codefreak directory in subpackages respectively to the packages of the classes they test.

8.2. End-to-end tests

End-to-end tests run with cypress. Cypress will be installed with npm automatically, but if you’re running on Linux you might need to install some additional libraries. Please refer to the official cypress documentation on how to install these dependencies.

The client/cypress/integration directory contains all the test files, the client/cypress/support directory contains files for customizing cypress (i.e. adding custom global commands). You will also find screenshots and videos of the test runs in subdirectories of client/cypress.

The client/cypress.json file contains global configurations for the end-to-end tests.

Please read the official cypress documentation for information on how to write these tests.

The end-to-end tests are run from within the client directory with the following commands:

$ npm run cypress:open  # opens the cypress gui where e2e tests can be run (with graphical output)
$ npm run cypress:run   # runs all e2e tests headless

9. Fix linting issues

$ ./gradlew spotlessApply
$ cd client
$ npm run fix

10. Making changes to the database schema

If you modify the entity layer under org.codefreak.codefreak.entity in a way that changes the database schema, you have to create a migration changelog. Code FREAK uses Liquibase for versioning the database schema. After you made your changes to the JPA entities, execute the script generateChangelog.sh in the project directory. It will create a new file under src/main/resources/db/changelogs. It contains differences between the latest schema version and the JPA entities. Modify the file if needed, for example if you create a new non-null column, add a value that is used for existing records. Keep in mind that the migration will be run on existing production databases. Please refer to the Liquibase documentation for more information on changelogs.

If you are on Windows, the script does not work on all emulated shells. Make sure to use one that is based on bash.

11. Releasing a new version

The project is split up into a main application and some auxiliaries that have their own repositories (e.g. the IDE). There are different release processes depending on the project. All repositories use semantic versioning.

Most projects produce a Docker image as their main artifact. The following tags are automatically created/updated by CI:

  • latest → latest released version

  • <major> → latest release with this major version

  • <major>.<minor> → latest release with this major and minor version

  • <major>.<minor>.<patch> → each specific release

  • canary → latest build from master (not necessarily released yet)

If you need at least a specific version of a Docker image as a dependency, you need to create a new major release of the depending AND the dependent project. This is necessary event if the dependent version is downwards compatible. This is a limitation of the tag system introduced above.

11.1. Advanced release process via CI

This is currently only used by the main application codefreak/codefreak.

To release a new version, manually trigger the Publish Release workflow with the new release version. Run the task on the appropriate major version branch (currently only master is supported).

11.2. Simple release process

This is used by all project that are not mentioned in the advanced release process section.

To release a new version, simply create a GitHub release (tag) in the form <major>.<minor>.<patch> (no prefix).