Go Back

L2B2 Platform Development Quickstart

This document outlines the steps to set up the development environment for the L2B2 Platform. The L2B2 Platform is a full-stack application that consists of a frontend and a backend.

The source code lives in two repositories:

  • l2b2-platform-frontend
  • l2b2-platform-backend

Additionally, the l2b2-platform repository contains the documentation and configuration files for the platform as a whole. It contains deployment configuration, development guidelines, and other resources.

This document will guide you through setting up the development environment for L2B2 Platform and solving any common issues you may encounter.

1. Setting up the fullstack development environment

1.1 Git

We use Git for version control. You need to have Git available on your machine to work with the codebase.

1.1.1 Git repositories access

To access the Git repositories, you need to have a GitLab account and be a member of the l2b2-platform group. Additionally, you need to have your SSH key added to your GitLab account.

1.1.2 Get a copy of the repository

git clone git@gitlab.com:ug_jn/projekty-ug/aplikacja-edu/l2b2-platform/l2b2-platform-frontend.git

After cloning, enter the repository directory:

cd l2b2-platform-frontend

1.1.3 Configure Commit Author

Configure the commit author before making any changes to the codebase. You are not allowed to commit code without a proper author. A proper author contains your full name and email address assigned by the university.

Do it by running the following commands:

git config user.name "Your Name"
git config user.email "y.name.000@studms.ug.edu.pl"

Please note that above commands will set the author for the local clone. If you make changes to the codebase on a different clone, you need to set the author again.

Please make sure you have added and verified the email address you'll use for commits in your GitLab account.

1.2 Dealing with line endings on Windows

If you are using MS Windows, you may encounter issues with line endings when working with the codebase. To avoid these issues, you can configure Git to force line endings to LF (Unix-style line endings) on commit and convert them back to CRLF (Windows-style line endings) on checkout.

Please note we use LF line endings in the codebase. Make sure you don't commit files with CRLF line endings.

Run the following commands to configure Git to handle line endings:

git config --global core.autocrlf true
git config --global core.eol lf

Additionally, you can configure your IDE and text editors to use LF line endings. On Visual Studio Code, you can set the files.eol setting to \n in your settings.json file.

{
  "files.eol": "\n"
}

1.3 Setting up Visual Studio Code for development

Copy Recommended VSCode Settings

To align your VSCode settings with the project's recommended configuration:

  1. Navigate to the .vscode directory at the root of the project.
  2. Copy the settings.json.sample file and rename the copy to settings.json.
  3. If desired, customize the settings.json with your personal preferences.

recommended plugins

2. Example Git scenarios

This section provides examples of common git scenarios you may encounter when working on the L2B2 Platform codebase.

Please note that the examples are provided to give you an idea of how to work with the codebase. Please make sure you are comfortable with the git workflow before making any changes to the codebase.

1.2.1 Making changes to the codebase

We use the l2b2-platform-frontend repository as an example.

Prerequisites:

  1. You have cloned the frontend repository.
  2. You have configured the commit author.
  3. You have made changes to the frontend codebase, and you want to commit them.

Steps:

  1. Enter the frontend repo directory:
cd l2b2-platform-frontend
  1. Create a new branch such as feature/STAR-XYZ-add-button-loading-state.
git checkout -b feature/STAR-XYZ-add-button-loading-state

You may know other commands to create a branch. Use the one you are comfortable with. Make sure the branch is based on the latest commit in the main branch.

  1. Commit your changes to the branch on the frontend codebase.
git add src/components/core/example/Button.tsx
git commit -m 'feat(core): Add loading state to Button component'
git push origin feature/STAR-XYZ-add-button-loading-state
  1. Create a merge request in the GitLab repository.

3. Running the fullstack application locally

The L2B2 Platform is a full-stack application. It requires running the frontend, backend, and Keycloak to work correctly. Keycloak is used for authentication and authorization of users.

The frontend and backend repositories contain instructions on how to run the frontend and backend applications locally. The l2b2-platform repository contains instructions on how to run Keycloak locally.

Please refer to the README files in the respective repositories for full instructions. Here's a brief overview:

  1. Run the frontend application:
cd l2b2-platform-frontend
docker compose -f docker-compose.dev.yml up --build --watch
  1. Run the backend application:
cd l2b2-platform-backend
docker compose -f docker-compose.dev.yml up --build --watch
  1. Run Keycloak:
cd l2b2-platform/local-development
docker compose up --build

After running the above commands, you should have the fullstack application running locally. You can access the frontend application at http://localhost:3000, and the backend application at http://localhost:8080/api/v0/. The Keycloak server is available at http://localhost:9000.

The frontend and backend servers will automatically rebuild and restart when you make changes to the codebase due to the --watch flag.

4. Useful L2B2 resources

You can access all important L2B2 resources under Living Lab - Tools & Links.

To learn more about L2B2 Platform Specification and its features in details, visit Platform specification - Master Document.

Important note: Make sure you have access to L2B2 Platform OneDrive resources using University of Gdańsk Office account.