Skip to content

Development

Jump to bottom
Jan Cizmar edited this page May 9, 2024 · 15 revisions

Running the backend

Prerequisites

The backend is written in Kotlin and Spring Boot. To run it, you will need:

  • Java 17
  • Docker

How to run the backend

1. Clone this repo

git clone git@github.com:tolgee/tolgee-platform.git

2. Run it

You can use

2a. Running with Gradle

./gradlew server-app:bootRun --args='--spring.profiles.active=dev'

2b. Running with Idea CE (free and open-source)

  1. Open the root dir in Idea CE
  2. Click the Edit configurations button in the top right corner
  3. Add a new configuration with the plus button
  4. Select Gradle
  5. Set run command to
server-app:bootRun --args='--spring.profiles.active=dev'
  1. Click the run/debug button in the top right corner with the newly created configuration

2c. Running with Idea Ultimate

  1. Open the root dir in Idea Ultimate
  2. Edit run configurations in the top right corner
  3. Duplicate Spring Boot auto-created configuration
  4. Rename to "Application Dev"
  5. Set Active profiles input to "dev"
  6. Save by clicking OK
  7. Select the "Application Dev" configuration in the dropdown.
  8. Run it with the Run/Debug button

Configuration

To configure Tolgee, create an empty file backend/app/src/main/resources/application-dev.yaml. In this file, you can override default configuration properties. You can check application-e2e.yaml for inspiration. To learn more about externalized configuration in Spring boot, read the docs.

Since we set the active profile to dev, Spring uses the application-dev.yaml configuration file.

Updating the database changelog

Tolgee uses Liquibase to handle the database migration. The migrations are run on every app startup. To update the changelog, run:

./gradlew diffChangeLog

Troubleshooting updating the changelog

  1. If you misspell the command and run diffChangelog, it will find the command, but it would fail, since liquibase changed the command name in the past. We have enhanced the diffChangeLog (with capital L) command, so you have to run that.

  2. Sometimes, Gradle cannot find a docker command to start the database instance to generate the changelog against. This happens due to some issue with setting the paths for Gradle daemon. Running the command without daemon fixes the issue. ./gradlew diffChangeLog --no-daemon

Running the Frontend

Prerequisites

  • node.js v18 or newer

How to run it

  1. go to webapp folder cd webapp
  2. Install npm packages "npm ci"
  3. Run it npm run start

Static analysis

For the frontend, there are npm tasks prettier and eslint, which you should run before every commit. Otherwise, the "Frontend static check" workflow will fail. You can also use prettier plugins for VS Code, Idea, or WebStorm.

To fix prettier issues and check everything is fine, run these commands in webapp dir:

npm run prettier
npm run tsc
npm run eslint

On the backend, there is Gradle task ktlintFormat, which helps you to format Kotlin code.

./gradlew ktlintFormat

Testing

The backend of Tolgee is tested with unit and integration tests. UI and its interaction with the backend are tested using E2E cypress tests.

Backend testing

To run backend tests, you can run Gradle test task

./gradlew test

Or you can select any integration test the code and run it via Idea CE or Idea Ultimate. It should just work out of the box.

E2E testing

Running E2E tests can be a bit more complicated.

Dependency installation

To just run it, you can execute the runE2e Gradle task. This command runs a complex task, which installs all dependencies and runs everything it needs.

./gradlew runE2e
  1. Instal npm packages in e2e dir
cd e2e
npm install
  1. Install npm packages in webapp dir

However, when developing you would probably also want to modify the frontend code or debug the backend. To do so, you have to run 4 different tasks at the same time.

  1. Run the web app with E2e settings
./gradlew runWebAppNpmStartE2eDev
  1. Run the E2e Docker services like fake SMTP server
./gradlew runDockerE2eDev
  1. Run the backend with e2e profile
./gradlew server-app:bootRun --args='--spring.profiles.active=e2e'

You can also do this by running the application with the E2e profile using Idea CE or Ultimate. Then you will be also able to debug the backend while running the tests, which can be pretty useful.

  1. Run the cypress
./gradlew openE2eDev

These 4 tasks have to run at the same time

When you are done, you can stop docker by running:

./gradlew stopDockerE2e
Clone this wiki locally