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:
-
Java JDK 8 or later (we recommend OpenJDK)
-
NodeJS 16 or later (https://nodejs.org/en/) with NPM v7
-
Docker (Linux) or Docker Desktop (Windows, MacOS) (https://docs.docker.com/get-docker/)
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. |
-
Obtain the source code of Code FREAK from GitHub:
git clone https://github.com/codefreak/codefreak.git
-
Generate the GraphQL schema:
./gradlew client:generate
(this will also install all backend and frontend dependencies) -
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 tohttp://localhost:8080
and see a 404 error page. -
Start the frontend inside the
client
directory withnpm 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:
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.
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
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).