Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• start.sh
• frontend/vite.config.ts
• backend/main.py
• QUICKSTART.md
• README.md
• frontend/package.json
• SUMMARY.md

This guide provides comprehensive instructions for setting up and running the SPK Kajek application in a local development environment. The application consists of a React-based frontend and a Python FastAPI backend, which work together to provide a decision support system for selecting cloud VPS servers.

The architecture is a classic client-server model where the frontend communicates with the backend via a REST API. The backend handles all business logic, including the TOPSIS algorithm calculations and data persistence through Excel and JSON files.

Sources: SUMMARY.md, README.md

1. System Architecture

The application is divided into two main components: a frontend client and a backend server.

• Frontend: A Single Page Application (SPA) built with React, TypeScript, and Vite. It runs on its own development server and is responsible for the user interface and user interactions.
• Backend: A RESTful API built with FastAPI and Python. It serves data, performs TOPSIS calculations, and manages user authentication.
• Data Layer: The backend interacts with local files for data storage, including an Excel file for vendor data and JSON files for user accounts and calculation history.

Sources: SUMMARY.md, backend/main.py:23-26

The following diagram illustrates the high-level architecture of the system.

This diagram shows the interaction between the user's browser, the Vite frontend server, the FastAPI backend server, and the file-based data storage.
Sources: SUMMARY.md, backend/main.py:23-26, frontend/vite.config.ts, QUICKSTART.md

2. Prerequisites

Before you begin, ensure you have the following software installed on your system.

Software	Minimum Version
Node.js	18+
Python	3.8+
npm	(Comes with Node.js)
pip	(Comes with Python)

Sources: QUICKSTART.md, README.md

3. Installation

The installation process involves setting up both the backend and frontend environments separately.

Installation Flow

This flowchart outlines the sequential steps for setting up the project dependencies.
Sources: QUICKSTART.md, README.md

3.1. Backend Setup (FastAPI)

1. Navigate to the backend directory.
2. Create and activate a Python virtual environment.
3. Install the required Python packages.

# Navigate to the backend directory
cd backend

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Linux/Mac:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Sources: QUICKSTART.md, README.md

3.2. Frontend Setup (React)

1. Navigate to the frontend directory.
2. Install the required Node.js packages.

# Navigate to the frontend directory
cd frontend

# Install dependencies
npm install

Sources: QUICKSTART.md, README.md, frontend/package.json

4. Running the Application

You can run the application using the provided start script (recommended) or by starting the backend and frontend servers manually in separate terminals.

4.1. Recommended Method: start.sh

The root directory contains a start.sh script that automates the startup process for both servers.

./start.sh

This script performs the following actions:

1. Starts the FastAPI backend server in the background.
2. Navigates to the frontend directory.
3. Starts the Vite development server for the frontend.

Sources: start.sh

4.2. Manual Method

If you prefer to run the servers manually, open two separate terminal windows.

Terminal 1: Start Backend

# Navigate to the backend directory
cd backend

# Activate the virtual environment if not already active
source venv/bin/activate

# Start the FastAPI server
uvicorn main:app --reload --port 8000

Sources: QUICKSTART.md, README.md

Terminal 2: Start Frontend

# Navigate to the frontend directory
cd frontend

# Start the Vite development server
npm run dev

Sources: QUICKSTART.md, README.md, frontend/package.json:7

5. Configuration

The application uses several configuration files and environment settings that can be adjusted.

5.1. Ports and URLs

The application runs on the following default ports:

Service	Default URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/docs
API Docs (ReDoc)	http://localhost:8000/redoc

• The frontend port is configured in frontend/vite.config.ts.
• The backend port is specified in the uvicorn command.
• The backend allows all origins (*) for CORS in development.

Sources: QUICKSTART.md, frontend/vite.config.ts:6, backend/main.py:14-15

5.2. Backend Configuration

Key backend settings are defined as global variables at the top of backend/main.py.

Variable	Default Value	Description
DATA_FILE	"TOPSIS_Input_Level.xlsx"	The Excel file used as the primary data source for vendors.
HISTORY_FILE	"calculation_history.json"	JSON file for storing past calculation results.
USERS_FILE	"users.json"	JSON file for storing user accounts and hashed passwords.
SECRET_KEY	"your-secret-key-here..."	Secret key for signing JWT tokens. Should be changed in production.
ALGORITHM	"HS256"	The algorithm used for JWT signing.
ACCESS_TOKEN_EXPIRE_MINUTES	1440 (24 hours)	The expiration time for JWT access tokens.

Sources: backend/main.py:23-31

5.3. Frontend Configuration

The primary configuration file for the frontend is frontend/vite.config.ts. It defines the Vite server settings, including the port and plugins used.

// frontend/vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/
export default defineConfig({
  server: {
    port: 5173, // Default frontend port
  },
  plugins: [react()],
})

Sources: frontend/vite.config.ts

6. Data Files

The backend relies on several files located in the backend directory for data persistence.

• TOPSIS_Input_Level.xlsx: Contains the list of VPS vendors and their specifications, categorized by levels. This is the main data source for the TOPSIS analysis.
• users.json: Stores user credentials. A default admin user is created if this file does not exist. Passwords are not stored in plaintext; they are hashed using PBKDF2.
• calculation_history.json: Stores a log of past TOPSIS calculations initiated by users.

Sources: backend/main.py:23-26, backend/main.py:101-112, generate_excel_level.py