App Hosting에 배포하는 다른 방법

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

소스에서 배포

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

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

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

필수 IAM 권한 및 인프라 설정

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

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

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

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

필수 설정 권한에는 다음이 포함됩니다.

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

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

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

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

활성 배포 권한에는 다음이 포함됩니다.

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

Firebase CLI를 사용하여 소스에서 배포

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

AI 도구를 사용하여 배포

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