Fabric 앱에 대한 정적 콘텐츠 호스팅

Fabric 앱에는 백 엔드 API와 함께 프런트 엔드 애플리케이션을 빌드, 패키지 및 제공하는 정적 콘텐츠 호스팅 서비스가 포함되어 있습니다. 정적 호스팅을 사용하도록 설정하면 CLI는 빌드된 자산을 Fabric 배포하고 사용자가 애플리케이션에 액세스할 수 있는 공용 URL을 제공합니다.

사전 요구 사항

  • 프런트 엔드 애플리케이션(예: React, Vue 또는 vanilla TypeScript)이 있는 Fabric Apps 프로젝트입니다.
  • 정적 출력(예 npm run build: )을 생성하는 빌드 명령입니다.

정적 호스팅 작동 방식

정적 호스팅을 사용하도록 설정하여 배포하는 경우 CLI는 다음 단계를 수행합니다.

  1. 구성된 빌드 명령(예: npm run build)을 실행합니다.
  2. 출력 폴더가 있고 파일이 포함되어 있는지 확인합니다.
  3. 모든 파일을 압축된 ZIP 보관 파일(최대 100MB)에 패키지합니다.
  4. Fabric 앱 호스트에 보관 파일을 업로드합니다.
  5. 애플리케이션에 액세스할 수 있는 공용 호스팅 URL을 반환합니다.

정적 호스팅 구성

rayfin/rayfin.yml 파일의 services 아래에 staticHosting 섹션을 추가합니다:

services:
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

구성 옵션

Option 필수 기본값 Description
enabled 예 — 정적 호스팅을 true 사용하도록 설정합니다.
folder 예 — root를 기준으로 한, 빌드된 정적 파일이 포함된 출력 폴더입니다.
root No 프로젝트 루트 프로젝트 루트를 기준으로 하는 프런트 엔드 프로젝트의 루트 디렉터리입니다.
buildCommand No — 패키징 전에 실행할 셸 명령입니다(예: npm run build).
indexDocument No — 디렉터리 요청에 사용할 기본 문서(예: index.html)입니다.

별도의 프런트 엔드 디렉터리가 있는 예제

프런트 엔드 코드가 하위 디렉터리에 있는 경우:

services:
  staticHosting:
    enabled: true
    root: frontend
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

이 구성은 출력 경로를 <project-root>/frontend/dist로 해석합니다.

정적 콘텐츠 배포

전체 배포

실행 npx rayfin up하면 정적 콘텐츠가 전체 스택 배포의 일부로 자동으로 배포됩니다.

npx rayfin up

CLI는 프런트 엔드를 빌드하고, 출력을 패키지하고, 백 엔드 구성과 함께 업로드합니다. 배포 후 CLI는 호스팅 URL을 출력하고 이를 .env.fabric-* 파일에 VITE_RAYFIN_HOSTING_URL로 기록합니다.

독립 실행형 정적 배포

staticapp deploy 하위 명령을 사용하여 전체 배포를 다시 실행하지 않고 정적 콘텐츠만 다시 배포합니다.

npx rayfin up staticapp deploy

이 명령은 프런트 엔드 코드만 변경하고 더 빠른 반복 주기를 원하는 경우에 유용합니다.

빌드 단계 건너뛰기

프런트 엔드를 이미 빌드하고 다시 빌드하지 않고 기존 출력을 배포하려는 경우:

npx rayfin up staticapp deploy --skip-build

자세한 로깅 정보 표시 사용

배포하는 동안 자세한 출력 표시:

npx rayfin up staticapp deploy --verbose

인증 콜백 구성

정적 호스팅 및 인증을 모두 사용하도록 설정하면 Rayfin CLI는 호스팅 URL에 따라 인증 콜백 URI를 자동으로 등록합니다.

예를 들어 호스팅 URL이 https://example.webapp.com이면 CLI는 다음 콜백 URI를 추가합니다:

services:
  auth:
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
      - https://example.webapp.com/auth/callback

인증 콜백 URI를 수동으로 구성할 필요가 없습니다. CLI는 구성을 업데이트하고 배포 중에 푸시합니다.

배포 크기 제한

  • 압축된 ZIP 보관 파일은 100MB를 초과하면 안됩니다.
  • CLI는 최대 압축을 사용하여 업로드 크기를 최소화합니다.
  • 빌드 출력이 제한을 초과하는 경우 다음을 수행하여 자산을 최적화합니다.
    • 프로덕션 빌드에서 원본 맵 제외
    • 큰 이미지 및 비디오 압축 또는 제거
    • 이진 파일을 묶는 대신 Fabric Apps 스토리지로 이동합니다.

전체 예제

정적 호스팅, 인증 및 데이터 서비스를 사용하도록 설정된 전체 rayfin.yml 구성:

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
    fabric:
      enabled: true
  data:
    enabled: true
    dialect: mssql
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

로컬에서 테스트

배포하기 전에 정적 빌드가 로컬에서 작동하는지 확인합니다.

  1. 프런트 엔드를 빌드합니다.

    npm run build

  2. 출력 폴더에 예상 파일이 포함되어 있는지 확인합니다.

    ls dist

  3. 로컬 정적 서버를 사용하여 빌드된 파일을 제공합니다.

    npx serve dist

  4. 서버에서 인쇄한 URL을 열고 애플리케이션이 올바르게 로드되는지 확인합니다.

배포 문제 해결

정적 폴더를 찾을 수 없음

CLI에서 정적 폴더가 존재하지 않는다고 보고하는 경우:

  • rayfin.yml의 folder 경로가 올바르며 root를 기준으로 한 상대 경로인지 확인하세요(root이 설정되지 않은 경우에는 프로젝트 루트를 기준으로).
  • 빌드 명령이 성공적으로 실행되고 예상 디렉터리에서 출력이 생성되었는지 확인합니다.

빈 정적 폴더

빈 출력 폴더는 일반적으로 빌드 명령이 실패했거나 출력을 생성하지 못했음을 의미합니다. 수동으로 빌드 명령을 실행하여 오류를 확인합니다.

npm run build

배포가 크기 제한을 초과합니다.

ZIP이 100MB를 초과하는 경우:

  • 불필요한 파일(원본 맵, 개발 자산)에 대한 빌드 출력을 검토합니다.
  • 프로덕션 빌드에서 원본 맵을 제외하도록 번들러를 구성합니다.
  • 큰 이진 파일을 Fabric Apps 스토리지로 이동합니다.

원격 엔드포인트가 구성되지 않음

이 명령에는 npx rayfin up staticapp deploy 기존 원격 배포가 필요합니다. 먼저 실행 npx rayfin up 하여 원격 엔드포인트를 구성한 다음, 후속 업데이트에 사용합니다 staticapp deploy .

관련 콘텐츠

  • Last updated on