Local Development

The local development setup of CVEScan Web is designed to provide a streamlined environment for developers to work on the project. It allows you to run the API server and WebUI locally, making it easy to test changes and develop new features.

As described in the services overview section, CVEScan Web is composed of several interconnected services. For local development, the setup is simplified by bypassing the use of a reverse proxy as the system's entry point. Instead, the API server and WebUI will communicate directly over HTTP, which is sufficient for development needs. Keycloak and PostgreSQL databases will run within Docker containers, while the API server, WebUI, and Keycloak Configurator will execute directly on the host machine. This configuration facilitates easier debugging and development.

Info

This guide is intended for developers who have access to the CVEScan Web source code repository. If you only have access to the CVEScan Web Dist repository, you will not be able to run the local development setup.

Prerequisites

Please ensure you have the following tools installed on your machine:

  • Git. This guide was tested with Git version 2.43.0.
  • Docker. This guide was tested with Docker version 28.2.2, build e6534b4.
  • Node.js. This guide was tested with Node.js version 22.13.0.

Also, you will need to have access to the CVEScan Web source code repository.

Setup

Before diving into the local development setup, take a moment to review the monorepo structure. This will provide you with a clear understanding of the project's organization, making it easier to navigate and work within the codebase.

1. Cloning the Repository

The first step is to clone the CVEScan Web repository.

git clone https://gitlab.com/witekio/rnd/theembeddedkit/cvescan/cvescan-web.git

You will be prompted for your GitLab credentials. As your repository access is managed through an access token, you may enter any value for the username, but you must provide your personal access token as the password to authenticate successfully.

Once cloned, navigate to the project directory using:

cd cvescan-web

2. Installing Dependencies

To get started, you need to install the project's dependencies. As this project is structured as an Nx monorepo, you can install all required dependencies by running the following command from the root directory of the project:

npm install

3. Setting Up Environment Variables

To set up the local development environment, you need to define several environment variables. Create a .env file in the project's root directory and include the following variables (ensure all CHANGE_ME placeholders are replaced with appropriate values before starting the application):

CVESCAN_DB_HOST="localhost"
CVESCAN_DB_PORT=5432
CVESCAN_DB_ADMIN_USER="postgres"
CVESCAN_DB_ADMIN_PASSWORD="CHANGE_ME"

CVESCAN_API_CORS_ORIGIN="http://localhost:4205,http://127.0.0.1:4205"
CVESCAN_API_EXPOSE_SWAGGER=true         # Default: false
CVESCAN_API_SKIP_INITIALIZATION=false   # Default: false

CVESCAN_API_DB_NAME="cvescan_api"
CVESCAN_API_DB_USER="cvescan_api_user"
CVESCAN_API_DB_PASSWORD="CHANGE_ME"
CVESCAN_API_ADMIN_EMAIL="CHANGE_ME"
CVESCAN_API_ADMIN_PASSWORD="CHANGE_ME"
CVESCAN_API_STORAGE_FOLDER=".storage" # Please add the folder name to the .nxignore file to avoid nx daemon crash when files get deleted


CVESCAN_KEYCLOAK_DB_NAME="cvescan_keycloak"
CVESCAN_KEYCLOAK_DB_USER="cvescan_keycloak_user"
CVESCAN_KEYCLOAK_DB_PASSWORD="CHANGE_ME"

CVESCAN_KEYCLOAK_ADMIN="CHANGE_ME"
CVESCAN_KEYCLOAK_ADMIN_PASSWORD="CHANGE_ME"

CVESCAN_KEYCLOAK_URL="http://localhost:3101/"   # end with /
CVESCAN_KEYCLOAK_REALM="dev"                    # if you change this value make sure to update the `environment.*.ts` files in the webui project
CVESCAN_JWT_AUDIENCE="cvescan_web"              # if you change this value make sure to update the `environment.*.ts` files in the webui project

CVESCAN_JWKS_URL="http://localhost:3101/realms/${CVESCAN_KEYCLOAK_REALM}/protocol/openid-connect/certs"
CVESCAN_JWT_ISSUER="http://localhost:3101/realms/${CVESCAN_KEYCLOAK_REALM}"

CVESCAN_WEBUI_HOST_URL="http://localhost:4205" # don't end with / , used by the keycloak configurator to set the valid redirect uri & web origins

CVESCAN_KEYCLOAK_ADMIN_CLIENT_SECRET="WILL_BE_SET_LATER"

Note

  • The CVESCAN_API_ADMIN_EMAIL and CVESCAN_API_ADMIN_PASSWORD variables are used to create the initial system admin user for the API server. You will use these credentials to log in to the WebUI and manage the application.
  • The CVESCAN_KEYCLOAK_ADMIN and CVESCAN_KEYCLOAK_ADMIN_PASSWORD variables are used to create the initial Keycloak admin user. This user will be used to access the Keycloak admin console.
  • All admin credentials specified in the .env file like the CVESCAN_API_ADMIN_EMAIL, CVESCAN_API_ADMIN_PASSWORD, CVESCAN_KEYCLOAK_ADMIN, CVESCAN_KEYCLOAK_ADMIN_PASSWORD and DB users and passwords are used only on the first run of the application. Changing these values after the initial setup will have no effect.

Additionally, if you are planning to run the E2E tests, you will need to add the following variables to the .env file:

CVESCAN_E2E_API_DB_NAME="cvescan_e2e_api"
CVESCAN_E2E_API_DB_USER="cvescan_e2e_api_user"
CVESCAN_E2E_API_DB_PASSWORD="CHANGE_ME"

# Please add the folder name to the .nxignore file to avoid nx daemon crash when running tests
CVESCAN_E2E_API_STORAGE_FOLDER=".e2e.storage"

CVESCAN_E2E_KEYCLOAK_REALM="e2e"

CVESCAN_E2E_JWT_ISSUER="http://localhost:3101/realms/e2e"
CVESCAN_E2E_JWT_AUDIENCE="cvescan_e2e"

CVESCAN_E2E_KEYCLOAK_ADMIN_CLIENT_SECRET="WILL_BE_SET_LATER"

4. Setting Up Optional Features

In addition to its core features, CVEScan offers optional (non-essential) features that can be enabled as needed.

Currently, the only available optional feature is the Jira integration. For detailed instructions on how to enable it, please refer to the Jira Integration Installation Guide.

5. Running PostgreSQL and Keycloak

To start PostgreSQL and Keycloak, utilize the docker-compose-dev.yml file provided for local development. This file is configured to launch both services in Docker containers. Run the following command to initiate the services:

docker compose -f docker-compose-dev.yml -p cvescan_dev up --build

The -f docker-compose-dev.yml option specifies the Docker Compose file to use, and the -p cvescan_dev option sets the project name to cvescan_dev.

When starting the database container for the first time, it will automatically initialize the two required databases for the API server and Keycloak, along with their respective users and passwords. These configurations are defined in the .env file, so ensure the file is properly set up before running the container. Refer to the Environment Variables section for more details. Note that this initialization occurs only during the first launch of the container, thus changes to the credentials or database names in the .env file after the initial setup will not affect the existing databases.

Note

  • A volume for the PostgreSQL database will be created, ensuring that the data persists even if the container is stopped or removed.
  • The PostgreSQL database will be accessible at localhost:5432 with the credentials specified in the .env file. You can use any PostgreSQL client to connect to the database and verify that it has been created successfully.
  • The Keycloak instance will be accessible at http://localhost:3101 with the credentials specified in the .env file. You can use the Keycloak admin console at http://localhost:3101/admin/master/console.

6. Configuring Keycloak

To integrate Keycloak with the API server and WebUI, you need to configure it appropriately. This process can be automated using the Keycloak Configurator tool. The configurator reads the necessary environment variables from the .env file and applies the required settings to Keycloak. The relevant variables are:

  • CVESCAN_WEBUI_HOST_URL
  • CVESCAN_JWT_AUDIENCE
  • CVESCAN_KEYCLOAK_REALM
  • CVESCAN_KEYCLOAK_URL
  • CVESCAN_KEYCLOAK_ADMIN
  • CVESCAN_KEYCLOAK_ADMIN_PASSWORD

To run the Keycloak Configurator, use the following command:

npm run start:kcc

This command will launch the Keycloak Configurator, which connects to the running Keycloak instance and applies the necessary configurations based on the environment variables. Additionally, it will generate a service account for the API server, enabling it to manage users and interact with Keycloak. The secret for this service account will be saved in the .secrets/.env file. You must manually transfer this secret from the .secrets/.env file to the .env file at the root of the project.

Note

To run the E2E tests later, you must configure a dedicated Keycloak realm for testing. You can do that by temporarily updating the .env file with the E2E test configuration, then running the Keycloak Configurator to create the new realm. Afterward, revert the .env file to its original state. Finally, ensure you copy the secret generated in the .secrets/.env file to the root .env file, as this is required for the E2E tests to work properly.

7. Running the API Server

Once Keycloak is configured, you can start the API server. The API server will connect to the PostgreSQL database and use the Keycloak instance for authentication. To start the API server, run the following command:

npm run start:api

This command will start the API server, which will listen for incoming requests on port 3100 by default. You can access the API server at http://localhost:3100.

Note: You can specify a different port by setting the CVESCAN_API_PORT environment variable in the .env file. If you change the port, make sure to update the apiPort variable in the apps/webui/src/environments/environment.ts file accordingly.

8. Running the WebUI

Finally, you can start the WebUI. The WebUI will connect to the API server and use Keycloak for authentication. To start the WebUI, run the following command:

npm run start:webui

The WebUI will start and be available on port 4205 by default. You can open it in your browser at http://localhost:4205.

Linting

To ensure code quality and consistency across the monorepo, you can run the linter on all projects using the following command:

npm run lint:all

Running unit tests

To run all the unit tests in the monorepo, you can use the following command:

npm run test:all

Running E2E Tests

To execute the E2E tests, ensure that both the database and Keycloak are running and properly configured as outlined in the previous sections. Additionally, verify that the required environment variables are correctly set in the .env file. Once everything is ready, you can initiate the E2E tests with the following command:

npm run test:e2e