Source Guard Frontend - Deployment Guide

Overview

Source Guard Frontend is a React-based web application built with TypeScript. It provides a user interface for managing vulnerability scanning and patch comparison for binary files.

Tech Stack:

React 18.2.0
TypeScript 4.9.3
Redux Toolkit for state management
Ant Design 5.8.4 for UI components
CRACO for custom webpack configuration
SASS for styling
Node.js 18.0.0

Prerequisites

Before starting development or deployment, ensure you have the following installed:

Node.js: Version 18.0.0 or higher
npm: Version 8.0.0 or higher (comes with Node.js)
Docker & Docker Compose: For containerized deployment (optional)
Git: For version control
PM2: For production process management (npm install -g pm2)
Yalc: For local component library development (npm install -g yalc)

Verify Installation

node --version  # Should show v18.0.0 or higher
npm --version   # Should show 8.0.0 or higher
pm2 --version   # Should show 5.0.0 or higher
yalc --version  # Should show 1.0.0 or higher

Development Setup

1. Clone the Repository

git clone <repository-url>
cd source-guard-frontend

2. Install Dependencies

npm install

Note: The postinstall script will automatically run patch-package to apply custom patches located in the patches/ directory.

3. Setup Component Library (Development)

This project uses Yalc for local development of the @Sparkle-Techbank/sourceguard-frontend-components library.

In the component library project:

# Navigate to your component library
cd /path/to/sourceguard-frontend-components

# Build the component library
npm run build

# Publish to yalc local store
yalc publish

In the frontend project:

# Link the local component library
yalc add @Sparkle-Techbank/sourceguard-frontend-components

# Install dependencies
npm install

Updating the component library during development:

# In the component library project
npm run build
yalc push

# The changes will automatically propagate to linked projects

To remove yalc link and use npm registry:

yalc remove @Sparkle-Techbank/sourceguard-frontend-components
npm install

4. Start Development Server

npm start

The development server will start on http://localhost:3001 (configured in craco.config.js).

5. Development Workflow

Development Best Practices:

Feature Development:
- Create a new feature branch from main
- Follow the ViewModel → UseCase → Repository → DataSource → API structure
- Use the component library for new UI components
Routing:
- All routing information is defined in ./src/App.tsx
- Route constants are in ./src/Core/Constants.ts
Component Development:
- New shared components should be created in the Source Guard Frontend Component Library
- Use Yalc to link the component library locally during development
- Import components from @Sparkle-Techbank/sourceguard-frontend-components
- Push updates with yalc push after building the component library

Environment Configuration

Base URL Configuration

The application's API base URL is configured in src/Core/Constants.ts:

const EnvType = {
  release: "", // Production (relative path)
  test: "http://localhost:8080", // Local testing
  preProdOne: "http://sg-pp1.sparkle-in-tech.com", // Pre-production 1
  preProdTwo: "http://sg-pp2.sparkle-in-tech.com", // Pre-production 2
  prod: "http://sg.sparkle-in-tech.com", // Production
  astri: "https://sourceguard.sscvip.astricsa.cf", // ASTRI environment
  astri_blind: "http://192.168.3.153:8080", // ASTRI blind environment
};

export const env = {
  BASE_URL: EnvType.astri, // Change this for different environments
  WORKFLOW_API_BASE: process.env.REACT_APP_WORKFLOW_API_BASE,
};

Environment Variables

A .env file is created in the root directory for environment-specific configurations:

# .env
REACT_APP_WORKFLOW_API_BASE=https://your-workflow-api-url.com

Important: Before deploying to production, ensure BASE_URL is set to EnvType.release in Constants.ts.

Building the Application

Development Build

For testing the production build locally:

npm run build

This command will:

Generate meta tags for cache busting (generate-meta-tag)
Build the application using CRACO

The build output will be in the build/ directory.

Build Output

The build process creates:

build/index.html - Main HTML file with inlined CSS
build/static/js/ - JavaScript bundles
build/static/media/ - Images and media files
build/meta.json - Cache busting metadata

Testing Production Build Locally

After building, you can serve the production build locally:

# Install serve globally if not already installed
npm install -g serve

# Serve the build folder
serve -s build -l 3001

Visit http://localhost:3001 to test the production build.

Deployment

Method 1: Native Deployment with PM2

This is the recommended method for production deployment on a native server.

Prerequisites

# Install PM2 globally
npm install -g pm2

# Install serve globally
npm install -g serve

Deployment Steps

Build the application:
```
npm install
npm run build
```

PM2 Configuration:

The PM2 configuration is located at deployment/config/ecosystem.config.js:

module.exports = {
  apps: [
    {
      name: "source-guard-frontend",
      script: "serve",
      args: "-s build -l 8080",
      cwd: "./",
      instances: 2,
      exec_mode: "cluster",
      watch: false,
      max_memory_restart: "500M",
      env: {
        NODE_ENV: "production",
      },
      error_file: "./logs/pm2-error.log",
      out_file: "./logs/pm2-out.log",
      log_date_format: "YYYY-MM-DD HH:mm:ss Z",
    },
  ],
};

Start the application with PM2:

# Create logs directory
mkdir -p logs

# Start the application
pm2 start deployment/config/ecosystem.config.js

# Save PM2 configuration
pm2 save

# Setup PM2 to start on system boot
pm2 startup

PM2 Management Commands:

# View application status
pm2 status

# View logs
pm2 logs source-guard-frontend

# Restart application
pm2 restart source-guard-frontend

# Stop application
pm2 stop source-guard-frontend

# Delete application from PM2
pm2 delete source-guard-frontend

# Monitor application
pm2 monit

Deployment Script

The native deployment script is located at deployment/scripts/deploy-native.sh.

Usage:

./deployment/scripts/deploy-native.sh

The script will:

Build the application
Create necessary directories
Start or reload the application with PM2
Save the PM2 configuration

Docker Deployment with Nginx

Method 2: Docker Compose Deployment (Recommended for Containerized Environments)

This method uses Docker Compose with Nginx as the web server for optimal performance and scalability.

Deployment Commands

# Build and start services
docker-compose -f deployment/docker/docker-compose.yml up -d --build

# View logs
docker-compose -f deployment/docker/docker-compose.yml logs -f frontend

# View real-time logs (last 100 lines)
docker-compose -f deployment/docker/docker-compose.yml logs -f --tail=100 frontend

# Stop services
docker-compose -f deployment/docker/docker-compose.yml down

# Stop and remove volumes
docker-compose -f deployment/docker/docker-compose.yml down -v

# Restart services
docker-compose -f deployment/docker/docker-compose.yml restart

# Rebuild and restart (force recreate)
docker-compose -f deployment/docker/docker-compose.yml up -d --build --force-recreate

Quick Commands (from project root)

For convenience, you can create a shell alias:

# Add to ~/.bashrc or ~/.zshrc
alias sgf-docker='docker-compose -f deployment/docker/docker-compose.yml'

# Then use:
sgf-docker up -d --build
sgf-docker logs -f frontend
sgf-docker down

Access the Application

Once deployed, access the application at:

Local: http://localhost:8080
Production: http://your-domain.com

Deployment Directory Structure

All deployment-related files are organized in the deployment/ directory:

deployment/
├── config/
│   └── ecosystem.config.js      # PM2 configuration
├── docker/
│   ├── Dockerfile               # Multi-stage Docker build
│   ├── docker-compose.yml       # Docker Compose configuration
│   └── nginx.conf               # Nginx server configuration
└── scripts/
    └── deploy-native.sh         # PM2 deployment script

Overview​

Prerequisites​

Verify Installation​

Development Setup​

1. Clone the Repository​

2. Install Dependencies​

3. Setup Component Library (Development)​

4. Start Development Server​

5. Development Workflow​

Environment Configuration​

Base URL Configuration​

Environment Variables​

Building the Application​

Development Build​

Build Output​

Testing Production Build Locally​

Deployment​

Method 1: Native Deployment with PM2​

Prerequisites​

Deployment Steps​

Deployment Script​

Docker Deployment with Nginx​

Method 2: Docker Compose Deployment (Recommended for Containerized Environments)​

Deployment Commands​

Quick Commands (from project root)​

Access the Application​

Deployment Directory Structure​

Overview

Prerequisites

Verify Installation

Development Setup

1. Clone the Repository

2. Install Dependencies

3. Setup Component Library (Development)

4. Start Development Server

5. Development Workflow

Environment Configuration

Base URL Configuration

Environment Variables

Building the Application

Development Build

Build Output

Testing Production Build Locally

Deployment

Method 1: Native Deployment with PM2

Prerequisites

Deployment Steps

Deployment Script

Docker Deployment with Nginx

Method 2: Docker Compose Deployment (Recommended for Containerized Environments)

Deployment Commands

Quick Commands (from project root)

Access the Application

Deployment Directory Structure