React

JavaScript 기반 React 프론트엔드 컴포넌트

React는 웹 프레임워크로, 자바스크립트 라이브러리의 하나로서 사용자 인터페이스를 만들기 위해 사용됩니다. Facebook에서 개발했고 오픈소스로 배포하고 있으며 싱글 페이지 애플리케이션이나 모바일 애플리케이션의 개발에 사용되고 있습니다. 현재 많이 활용되고 있는, 웹/앱의 View를 개발할 수 있도록 하는 인기있는 라이브러리입니다.

React는 아래와 같은 특징을 가지고 있습니다.

Data Flow

Component 기반 구조

Virtual Dom

Props and State

JSX

Turaco에서는 이러한 React 프레임워를 이용하여 쉽게 개발 할 수 있도록 드래그 & 드롭 방식을 통해 쉽게 개발환경을 제공하고 있습니다.

React 컴포넌트를 적용하면 구조화된 코드 템플릿을 제공하여 빠르게 개발할 수 있는 환경을 개발자에게 제공합니다. 또한 배포 이후 개발자들의 개발 코드를 즉시 배포할 수 있도록 배포 파이프라인(CI/CD)도 제공합니다.

본 챕터에서는 React 컴포넌트 사용법에 대해 설명합니다.

컴포넌트 배치

React 컴포넌트는 아키텍처 설계 화면 (이하 디자이너 화면)에서 좌측에 위치한 컴포넌트 목록에서 프론트엔드 카테고리에 있습니다.

설계화면 왼쪽 컴포넌트 리스트 화면에서 React 컴포넌트를 선택 후 디자이너 화면으로 드래그 & 드롭합니다.

컴포넌트배치

배치된 React 컴포넌트에 대한 이름과 설명을 입력합니다.
이름과 설명은 필수 입력값이며 입력하지 않으면 확인 버튼이 활성화되지 않습니다.
입력된 이름과 설명은 아키텍처 설계 및 생성되는 리소스에 사용됩니다.

포트 설정

3. 포트 정보는 3가지 정보를 반드시 입력해야 합니다.
미 입력시 컨테이너 실행 후 정상적으로 접속이 되지 않을 수 있습니다.

프로토콜 -> 통신시 사용할 프로토콜 설정(현재는 http만 지원)
입력포트 -> 서비스 입력 포트로 사용
타겟포트 -> 서비스 출력 포트이며 컨테이너의 입력 포트로 주입

입력된 정보는 애플리케이션 생성시 배포를 위한 Helm 차트 생성에 사용됩니다.
포트 정보를 입력하지 않으면 Helm 차트 리소스가 만들어지지 않거나 배포 시 애플리케이션이 정상적으로 동작하지 않을 수 있습니다.

스토리지 설정

컨테이너는 로컬 스토리지를 사용할 수 있으나 컨테이너의 특성상 재시작되거나 삭제되는 경우 저장된 데이터가 같이 삭제됩니다.
이러한 특성 때문에 외부에 영구 볼륨을 설정하고 저장을 해야 데이터가 유실되지 않고 보관이 됩니다.

Turaco에서는 운영 환경에서 많이 사용하는 2가지 스토리지 클래스를 지원합니다.

NFS 기반의 스토리지 클래스 (tlc-nfs-sc)

Disk 기반의 스토리지 클래스 (tlc-block-sc)

4. 스토리지 설정시 아래와 같이 3개의 속성이 있습니다.

접근 모드 -> 스토리지 접근 모드
볼륨 크기 -> 볼륨 크기 입력(ex. 5Gi)
스토리지 클래스 -> 스토리지 클래스 이름 입력(기본값 유지 추천)

React 컴포넌트에서는 접근모드는 ReadWriteOnce로 고정되어 있으며 변경할 수 없습니다.
스토리지 클래스는 NFS 또는 Disk 기반의 스토리지 클래스 이름을 입력해야 하며 잘못된 값을 입력할 경우 정상적으로 배포가 되지 않을 수 있습니다.

SSR 적용 가이드

React 템플릿은 Vite 기반으로 SSR(Server-Side Rendering) 구성을 확장할 수 있습니다. 자세한 Vite SSR 동작 방식은 Vite 서버 측 렌더링 공식 가이드를 참고합니다.

현재 Turaco React 템플릿은 기본적으로 CSR(Client-Side Rendering) 방식으로 동작합니다. SSR을 적용하더라도 Jenkins CI/CD의 기본 흐름은 재사용하는 것을 원칙으로 합니다. SSR 차이는 주로 템플릿 코드, package.json 스크립트, Dockerfile 런타임 구성에서 흡수합니다.

기본 구조

index.html
server.js
src/
  main.tsx
  entry-client.tsx
  entry-server.tsx

entry-client.tsx: 브라우저에서 hydrate 또는 mount를 수행합니다.
entry-server.tsx: React SSR API로 HTML 문자열을 렌더링합니다.
server.js: 요청 URL을 기준으로 템플릿 HTML에 SSR 결과를 주입합니다.
index.html: 서버 렌더링 결과가 들어갈 placeholder를 둡니다. 예:

빌드 스크립트

기존 Jenkinsfile은 podman build --build-arg PROFILE=$PROFILE ... 방식으로 Dockerfile을 빌드합니다. Jenkinsfile을 바꾸기보다 기존 CI가 호출하는 build/build:dev 스크립트 이름을 유지합니다.

{
  "scripts": {
    "build": "npm run build:ssr",
    "build:dev": "npm run build:ssr",
    "build:client": "vite build --outDir dist/client --ssrManifest",
    "build:server": "vite build --outDir dist/server --ssr src/entry-server.tsx",
    "build:ssr": "npm run build:client && npm run build:server",
    "start": "node dist/server/server.js"
  }
}

배포 기준

Jenkinsfile stage 이름과 순서는 변경하지 않습니다.
Dockerfile은 기존처럼 ARG PROFILE을 받고 npm run build:${PROFILE}를 우선 실행한 뒤 없으면 npm run build로 fallback합니다.
Dockerfile runtime stage만 Nginx 정적 서빙에서 Node SSR 서버 실행으로 바꿉니다.
이미지 태그, registry login, push, Helm values 업데이트, ArgoCD sync는 기존 Jenkinsfile 흐름을 그대로 사용합니다.
Helm chart는 기존 frontend deployment 템플릿을 최대한 유지하되, SSR 컨테이너의 listen port와 health check만 필요한 경우 조정합니다.

컴포넌트 배치​

React 컴포넌트는 아키텍처 설계 화면 (이하 디자이너 화면)에서 좌측에 위치한 컴포넌트 목록에서 프론트엔드 카테고리에 있습니다.​

포트 설정​

스토리지 설정​

SSR 적용 가이드​

기본 구조​

빌드 스크립트​

배포 기준​