App Hosting에 배포하는 다른 방법

대부분의 경우 Firebase Console에서 자동 출시 또는 수동으로 트리거된 출시 를 사용하는 것이 좋습니다. 하지만 더 맞춤설정된 배포 흐름을 사용해야 할 수도 있습니다. App Hosting에는 맞춤 배포를 위한 여러 옵션이 있습니다.

소스에서 배포

소스에서 배포하면 영구적인 GitHub 연결 없이 애플리케이션의 소스 코드와 구성을 App Hosting으로 직접 푸시할 수 있습니다.

소스에서 배포할 때 App Hosting은 소스 코드를 Google Cloud Storage 버킷에 업로드하고, Cloud Build에서 프레임워크의 빌드 명령어를 실행하고, 컴파일된 아티팩트를 Cloud Run 및 Cloud CDN에 배포합니다. GitHub 배포와 마찬가지로 로컬 소스 배포에도 동일한 빌드 프로세스가 사용됩니다. 프로젝트에 .gitignore 파일이 있으면 이 파일 내에 나열된 파일과 폴더가 배포에서 제외됩니다.

Firebase CLI 또는 Firebase console 을 사용하여 로컬 소스에서 배포할 수 있습니다.

필수 IAM 권한 및 인프라 설정

Firebase CLI와 Firebase Console은 모두 동일한 백엔드 인프라를 사용하여 소스 보관 파일을 저장하고 빌드하므로 동일한 IAM 권한 요구사항이 두 배포 방법 모두에 적용됩니다.

정확한 요구사항은 특정 위치 (리전)에 처음으로 배포하는지 여부에 따라 다릅니다. 권한에 관한 자세한 내용은 Firebase IAM 개요 및 특정 Firebase App Hosting 권한을 참고하세요.

초기 온보딩 권한 (위치에 처음 배포)

프로젝트 위치에서 처음으로 로컬 소스 배포가 시작되면 Hosting은(는) 보관 파일을 저장할 GCS 버킷을 프로비저닝하고 Hosting 서비스 에이전트가 보관 파일에 액세스할 수 있는 권한을 부여해야 합니다. 이러한 작업은 프로젝트 수준의 관리 작업이므로 프로젝트 소유자 또는 IAM 관리자 권한이 필요합니다. 기본 편집자 또는 뷰어 역할이 있는 사용자는 이 초기 설정을 실행할 수 없으며 차단됩니다.

기본 요건 설정 권한은 다음과 같습니다.

  • Storage API 사용 설정: serviceusage.services.enable
  • 소스 버킷 만들기: storage.buckets.create 및 storage.buckets.list
  • 서비스 에이전트 구성: 빌드 중에 업로드된 코드를 가져올 수 있도록 읽기 액세스 권한 (roles/storage.objectViewer)을 부여하는 resourcemanager.projects.setIamPolicyHosting

초기 배포의 경우 GCS 버킷은 30일의 수명 주기로 생성되며, 그 후 버킷이 삭제됩니다. 하지만 Cloud Console의 Cloud Storage -> 버킷 -> 수명 주기 -> 규칙 에서 이 기간을 관리할 수 있습니다. 객체 수명 주기 관리를 참고하세요.

후속 배포 권한 (위치가 초기화된 후)

소스 버킷 및 역할 바인딩이 위치에 대해 초기화되면 (초기 CLI 배포 또는 콘솔 설정 중 하나를 통해) 일반 개발자, 편집자 또는 App Hosting 관리자 가 업데이트를 배포할 수 있습니다. 일상적인 배포에는 프로젝트 수준의 관리 권한이 필요하지 않습니다.

활성 배포 권한은 다음과 같습니다.

  • 버킷 확인: storage.buckets.list
  • 소스 보관 파일 업로드: storage.objects.create
  • 빌드 및 출시 트리거: 표준 Hosting 권한 (apphosting.builds.create 및 apphosting.rollouts.create)

FirebaseCLI를 사용하여 소스에서 배포

Firebase CLI v14.4.0 이상을 사용하면 앱의 소스 코드와 구성을 로컬 머신에서 Firebase로 직접 푸시할 수 있습니다. 보안 규칙 또는 함수와 같은 다른 Firebase 배포를 이미 관리하고 있으며 웹 앱과 백엔드 서비스를 단일 CLI 명령어로 함께 배포하려는 경우에 유용합니다.

기본 요건

  • 프로젝트가 Blaze 요금제 에 있어야 합니다.
  • firebase-tools 버전 14.4.0 이상을 실행해야 합니다.

배포 단계

  1. 로컬 프로젝트 디렉터리에서 firebase init apphosting을 실행합니다.
  2. 메시지가 표시되면 기존 프로젝트 사용 을 선택하고 대상 Firebase 프로젝트를 선택합니다.
  3. 배포할 새 백엔드 또는 기존 백엔드를 선택합니다. 이 단계에서는 로컬 디렉터리의 Hosting 배포를 설정하고 구성 세부정보를 묻는 메시지를 표시합니다.
    • 배포할 백엔드의 ID
    • 새 백엔드를 만드는 경우 배포할 리전
    • 애플리케이션 코드의 루트 디렉터리 경로
    • 선호하는 Node.js 런타임. 버전이 지정된 런타임을 선택하면 기본 이미지 자동 업데이트 (ABIU) 가 기본 환경에 보안 패치를 자동으로 적용할 수 있습니다.
  4. App Hosting은 배포 환경설정을 firebase.json에 저장하고, 로컬 프로젝트에 파일이 아직 없는 경우 파일을 만듭니다. 초기화가 완료되면 firebase deploy를 실행하여 소스 코드를 배포합니다.

firebase.json 예시

{
  "apphosting": [
    {
      "backendId": "my-backend",
      // rootDir specifies the directory containing the app to deploy, but the entire
      // parent directory of firebase.json will be zipped and uploaded to ensure that
      // dependencies outside of the app directory will be available at build time.
      "rootDir": "./my-app",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log",
        "functions"
      ]
    }
  ]
}

Firebase Console을 사용하여 배포 (Zip 업로드)

Firebase 콘솔은 압축된 소스 보관 파일을 직접 업로드하여 애플리케이션을 배포할 수 있는 그래픽 인터페이스를 제공합니다. GitHub를 사용하지 않거나 다른 CI/CD 설정을 선호하는 경우 GitHub 연결 흐름의 대안으로 사용할 수 있습니다.

보관 파일 업로드는 초기 백엔드 생성 중에 또는 기존 백엔드에서 수동 출시를 만들 때 실행할 수 있습니다. 여기에는 Firebase CLI를 사용하여 원래 배포된 백엔드가 포함됩니다.

지원되는 형식

콘솔 업로더는 두 가지 압축된 보관 파일 형식을 기본적으로 검증하고 허용합니다.

  • .zip
  • .tgz

이러한 형식은 파일 업로더의 설명 텍스트에 명시적으로 표시됩니다.

배포 단계

옵션 A: 초기 백엔드 온보딩 중
  1. 소스 선택: 백엔드 생성 마법사의 '앱을 가져오려면 어떻게 해야 하나요?' 단계에서 Zip 업로드를 선택합니다.
  2. 온보딩 준비: '다음'을 클릭하면 백그라운드 준비 흐름이 트리거되어 Storage API를 순차적으로 사용 설정하고, 올바른 역할이 설정되어 있는지 확인하고, 버킷을 upsert합니다. UI에 동적 상태 메시지가 포함된 로딩 스피너가 표시됩니다. "API 사용 설정 중..." "권한 확인 중..." 및 "버킷 준비 중...".
    • 오류 처리 및 가드레일: 준비 단계가 실패하면 (예: 소유자가 아닌 사용자가 IAM 권한이 부족하여 403 PERMISSION_DENIED를 수신하는 경우) UI에 프로젝트 소유자에게 문의하라는 전용 경고가 표시됩니다. 스테퍼 탐색이 엄격하게 잠기며, 문제가 해결될 때까지 '다음' 버튼과 최종 '완료 및 배포'가 사용 중지된 상태로 유지됩니다.
  3. 파일 업로드: 준비가 완료되면 보관 파일을 선택하거나 파일 업로더 구성요소로 드래그합니다.

  4. 설정 구성: 앱 루트 디렉터리 를 지정합니다 (기본값은 /).

  5. 완료 및 배포를 클릭합니다. 보관 파일 업로드는 일회성 작업이며 기능 백엔드를 보장하기 위해 배포가 즉시 이어져야 하므로 독립형 '완료' 버튼은 zip 업로드에 사용 중지됩니다.

옵션 B: 수동 출시 만들기
  1. 대화상자 열기: Hosting 대시보드에서 출시 만들기를 클릭합니다.
  2. 소스 선택: 대화상자의 스테퍼에서 Zip 업로드를 선택합니다. 백엔드에 기존 GitHub 연결이 없으면 'GitHub' 옵션이 사용 중지됩니다.
  3. 준비 및 업로드: 선택하면 동일한 백그라운드 준비 흐름 ("API 사용 설정 중...", "권한 확인 중...", 및 "버킷 준비 중...")이 트리거됩니다. 성공하면 업로더를 사용하여 보관 파일을 드래그하거나 선택하고, 앱 루트 디렉터리를 지정하고, 배포를 클릭하여 빌드 및 출시를 트리거합니다.

Terraform을 사용하여 배포

빌드 프로세스와 배포된 환경을 더 세부적으로 제어해야 하는 경우 Terraform을 사용하여 배포할 수 있습니다. Terraform을 사용하면 선언적 구성 파일을 사용하여 App Hosting 리소스를 정의하고 관리할 수 있으며, 자체 사전 빌드된 컨테이너 이미지를 App Hosting에 직접 배포할 수 있습니다. App Hosting에서 소스 코드를 빌드하는 대신

Terraform을 처음 사용하는 경우 Terraform 및 Firebase 시작하기를 참고하세요. Terraform에 이미 익숙한 경우 샘플 구성 파일 및 기타 App Hosting 리소스를 시작할 수 있습니다.

CI/CD를 위한 GitHub 연결 설정

Firebase FirebaseConsole의 백엔드 설정에 있는 배포 탭에서 언제든지 GitHub 저장소를 연결할 수 있습니다. 이렇게 하면 로컬 환경에서 앱 프로토타입을 배포한 후 준비가 되면 자동화된 CI/CD 파이프라인으로 전환할 수 있습니다.

AI 도구를 사용하여 배포

Firebase Studio은(는) 2027년 3월 22일에 지원 종료됩니다. App Hosting 백엔드는 영향을 받지 않지만 게시 버튼은 Firebase Studio 지원 종료됩니다. URL을 변경하지 않고 업데이트를 계속 게시하려면 프로젝트를 마이그레이션하세요. 마이그레이션 방법 알아보기.