- 1. Programming Languages and Frameworks
- 2. Directory Structure
- 3. Development Setup Steps
- 4. Building Code FREAK
- 5. Configuration
- 6. Run the application
- 7. Authentication
- 8. Running tests
- 9. Fix linting issues
- 10. Making changes to the database schema
- 11. Releasing a new version
|This guide is only for developers! If you would like to deploy Code FREAK to your servers please check out the admin installation guide.|
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:
At its root the Code FREAK code base is a Gradle project.
All backend code resides inside the
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.
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 to
http://localhost:8080and see a 404 error page.
Start the frontend inside the
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.
Build Code FREAK by using
This will generate the Docker image
cfreak/codefreak on your local machine.
Create the file
For documentation on how to configure the server see
in the same directory.
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
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
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.
docker CLI commands (like
docker ps) you can connect to the virtual machines terminal with
In the established connection all docker commands will point the the VM’s Docker daemon.
If you use IntelliJ simply start the
CodeFreakApplication Spring Boot application.
For Gradle run the command
The application is started at
The following sample users are pre-configured for development.
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.
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.
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.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
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
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
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.|
This is currently only used by the main application
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).