Skip to content

Vitality Getting Started

Jump to bottom
Héla Ben Khalfallah edited this page Jan 14, 2025 · 27 revisions

This page provides a comprehensive guide to setting up, installing, and working on the Vitality project. Vitality is a centralized telemetry system designed to integrate multiple tools, enabling better debugging, performance tracking, and user experience improvements. Follow the instructions below to get started.

Main Technologies Used

Frontend

Frontend Back Office (BO)

Backend

Installation Guide

Prerequisites

  1. Install PostgreSQL for your OS.
  2. Install pgAdmin 4 for your OS.
  3. Install Node.js using nvm (minimum version 22.11.0).
  4. Install pnpm using: 
    npm i -g pnpm
    Minimum version: 9.15.4.

Database Configuration

1. Create a Role in PostgreSQL

  • Open your terminal and type psql.

  • Use \du to list existing roles.

  • If your_name does not exist, create a role using the following command:

    CREATE ROLE "your_name" LOGIN PASSWORD 'your_password';

    Example:

    CREATE ROLE "john_dupon" LOGIN PASSWORD 'awesome_password';

    🔴 Note: The postgres role should exist by default as a superuser.

2. Set Up a New Connection in pgAdmin 4

  • Open pgAdmin 4 and create a new server connection.
  • Use the following details:
    • Name: v6y_database
    • Hostname: localhost

🔴 Common Error:

  • -bash: psql: command not found

  • Add PostgreSQL to your system's PATH:

    export PATH=/path/to/PostgreSQL/bin:$PATH

Project Installation

1. Clone the Repository

git clone https://github.com/ekino/v6y.git

2. Navigate to the Project Directory

cd v6y

3. Install Dependencies with PNPM

pnpm install

This installs dependencies for all monorepo modules.

4. Configure Environment Variables

  • In these directories: v6y, v6y-libs/core-logic, front, front-bo, bff, and bfb-*, create an .env file according to the env-template file content.

  • Refer to GitLab Personal Access Tokens and GitHub Personal Access Tokens for generating tokens.

  • Initialize the database by running the following command from the root folder:

    pnpm run init-db

Running the Application

Frontend Only

The Frontend is responsible for displaying the user interface of the application, while the Backend for Frontend (BFF) acts as an intermediary layer between the frontend and backend systems. It handles data aggregation and communication with the backend services, ensuring that the frontend receives the required data in an optimized format.

To start these components:

  1. Start the Backend for Frontend:

    cd v6y-apps/bff
pnpm start:dev

  2. Start the Frontend:

    cd v6y-apps/front
pnpm start:dev

Frontend Back Office (BO) Only

The Frontend Back Office (BO) is designed for administrative tasks, providing tools for managing application configurations, user accounts, and other backend settings. Like the main frontend, it communicates with the Backend for Frontend (BFF) for optimized data handling.

To start these components:

  1. Start the Backend for Frontend:

    cd v6y-apps/bff
pnpm start:dev

  2. Start the Frontend Back Office:

    cd v6y-apps/front-bo
pnpm start:dev

Backend Only

The Backend consists of various services that perform core application logic, including data processing, analysis, and storage. These services communicate with the Backend for Frontend (BFF) to deliver the required data to both frontend and back-office applications.

Start the following components:

  1. Static Code Auditor:

    cd v6y-apps/bfb-static-code-auditor
pnpm start:dev

  2. Main Analyzer:

    cd v6y-apps/bfb-main-analyzer
pnpm start:dev

  3. Backend for Frontend (BFF):

    cd v6y-apps/bff
pnpm start:dev

🔵 GraphQL Playground: Access the playground at http://localhost:4001/v6y/graphql for testing queries and mutations.

Initial Database Data

The initial database data is critical for the application to function correctly as it provides the foundational data structures and default configurations required for core features. For example, it may include:

  • Default Roles and Permissions: Ensuring proper access control mechanisms are in place.
  • Configuration Settings: Predefined settings to bootstrap the application.
  • Demo or Sample Data: Allows you to test and verify features during development.

Steps to Load Initial Data:

  1. Import the tar file into your PostgreSQL database.

  2. To use the Front, Front-BO, or query the BFF, create a superadmin account in the database. Use the following SQL command to insert the account:

    INSERT INTO accounts (username, email, password, role, created_at, updated_at, applications)
VALUES (
  'superadmin', 
  '[email protected]', 
  '$2a$10$fSDUAlp4s8gJNc7HtZdMdeevQHAyRgCy6knbL1QQz3pHstXSbWm0W', 
  'SUPERADMIN', 
  NOW(), 
  NOW(), 
  ARRAY[]::integer[]
);

  3. Include a Bearer token in the Authorization header for every query sent to the BFF. Obtain this token using the login query.

Contribution Guide

Typical Contributions

Contributing to this project can involve a variety of tasks, including:

  1. Bug Fixes: Identifying and resolving issues in the codebase.
  2. Feature Development: Implementing new features or improving existing functionality.
  3. Documentation: Enhancing project documentation to improve clarity and usability.
  4. Code Reviews: Reviewing pull requests to ensure code quality and adherence to guidelines.
  5. Testing: Writing unit tests, integration tests, or performance tests to ensure application stability.
  6. UI/UX Improvements: Refining the frontend design and improving user experience.

Getting Started

  1. Familiarize yourself with the project's structure and workflows.
  2. Check the GitHub Issues for tasks labeled as good first issue or help wanted.
  3. Follow the Contribution Guide for detailed instructions on submitting your contributions.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For further assistance, contact our support team or open an issue on GitHub.

image

Clone this wiki locally