Firebase Hosting과 GitHub Actions로 Docusaurus 자동배포 구축하기

Firebase Hosting과 GitHub Actions를 활용해서 Docusaurus 블로그를 자동으로 배포하는 방법을 단계별로 알아보겠습니다. 이 가이드를 따라하면 코드를 푸시할 때마다 자동으로 사이트가 배포되는 완전한 CI/CD 파이프라인을 구축할 수 있습니다.

🚀 왜 Firebase Hosting인가?

Firebase Hosting은 Google에서 제공하는 정적 웹사이트 호스팅 서비스로, 다음과 같은 장점이 있습니다:

• 무료 SSL 인증서 자동 제공
• 전 세계 CDN 을 통한 빠른 로딩 속도
• 커스텀 도메인 연결 지원
• GitHub Actions와 완벽한 연동
• Preview 배포 기능으로 PR별 미리보기 제공

📋 사전 준비사항

시작하기 전에 다음 사항들이 준비되어 있어야 합니다:

• Docusaurus 프로젝트 (GitHub 저장소)
• Firebase 계정
• Node.js 18 이상

1️⃣ Firebase 프로젝트 설정

Firebase 프로젝트 생성

1. Firebase Console에 접속
2. 새 프로젝트 만들기 클릭
3. 프로젝트 이름 입력 (예: my-blog-site)
4. Google Analytics 설정 (선택사항)
5. 프로젝트 생성 완료

Hosting 기능 활성화

1. 좌측 메뉴에서 Hosting 클릭
2. 시작하기 버튼 클릭
3. Firebase CLI 설치 안내 확인 (나중에 진행)

2️⃣ Firebase CLI 및 설정 파일 준비

Firebase Tools 설치

프로젝트 루트에서 Firebase Tools를 개발 의존성으로 설치합니다:

npm install --save-dev firebase-tools

Firebase 설정 파일 생성

firebase.json 파일을 생성합니다:

{
  "hosting": {
    "public": "build",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ],
    "headers": [
      {
        "source": "/static/**",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "public, max-age=31536000, immutable"
          }
        ]
      },
      {
        "source": "**/*.@(html|js|css)",
        "headers": [
          {
            "key": "Cache-Control", 
            "value": "public, max-age=3600"
          }
        ]
      }
    ],
    "cleanUrls": true,
    "trailingSlash": false
  }
}

.firebaserc 파일도 생성합니다:

{
  "projects": {
    "default": "your-firebase-project-id"
  }
}

캐시 설정 설명

위 설정에서 주목할 점들:

• 정적 파일 (/static/**): 1년 캐시 - 변경되지 않는 이미지, 폰트 등
• HTML/JS/CSS: 1시간 캐시 - 자주 업데이트되는 파일들
• Clean URLs: .html 확장자 없이 접근 가능
• SPA 지원: 모든 경로를 index.html로 리라이트

3️⃣ GitHub Actions 워크플로우 설정

워크플로우 파일 생성

.github/workflows/deploy.yml 파일을 생성합니다:

name: Deploy to Firebase Hosting

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    environment: production
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
        cache: 'npm'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Run type check
      run: npm run typecheck
      
    - name: Run linting
      run: npm run lint
      
    - name: Build project
      run: npm run build
      
    - name: Deploy to Firebase Hosting (Preview)
      if: github.event_name == 'pull_request'
      uses: FirebaseExtended/action-hosting-deploy@v0
      with:
        repoToken: '${{ secrets.GITHUB_TOKEN }}'
        firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
        projectId: your-firebase-project-id
        
    - name: Deploy to Firebase Hosting (Production)
      if: github.event_name == 'push' && github.ref == 'refs/heads/master'
      uses: FirebaseExtended/action-hosting-deploy@v0
      with:
        repoToken: '${{ secrets.GITHUB_TOKEN }}'
        firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
        projectId: your-firebase-project-id
        channelId: live

워크플로우 특징

• 품질 검사: 타입 체크와 린팅을 통한 코드 품질 보장
• 조건부 배포: PR은 프리뷰, master 푸시는 프로덕션 배포
• 캐시 활용: npm 의존성 캐시로 빌드 시간 단축

4️⃣ GitHub Secrets 설정

Firebase Service Account 키 생성

터미널에서 Firebase에 로그인하고 Service Account 키를 생성합니다:

# Firebase 로그인
npx firebase login

# Service Account 키 생성
npx firebase service:account --project your-firebase-project-id

또는 Firebase Console에서:

1. 프로젝트 설정 → 서비스 계정 탭
2. 새 비공개 키 생성 클릭
3. JSON 파일 다운로드

GitHub Environment 설정

1. GitHub 저장소 → Settings → Environments
2. New environment 클릭
3. 환경 이름: production
4. Environment secrets에서 Add secret 클릭
5. Name: FIREBASE_SERVICE_ACCOUNT
6. Value: 다운로드한 JSON 파일의 전체 내용

5️⃣ 커스텀 도메인 연결 (선택사항)

도메인 추가

1. Firebase Console → Hosting
2. Add custom domain 클릭
3. 도메인 입력 (예: myblog.com)

DNS 설정

Firebase에서 제공하는 IP 주소로 A 레코드를 설정합니다:

Type: A
Name: @
Value: 199.36.158.100

Type: A  
Name: @
Value: 199.36.158.101

6️⃣ 배포 테스트

로컬에서 테스트

# 빌드 및 로컬 Firebase 서버 실행
npm run build
npx firebase serve

# 또는 package.json에 스크립트 추가
npm run firebase:serve

자동배포 테스트

1. 코드를 수정하고 master 브랜치에 푸시
2. GitHub Actions 탭에서 워크플로우 실행 확인
3. 성공하면 Firebase에 자동 배포 완료

PR 프리뷰 테스트

1. 새 브랜치 생성 후 PR 생성
2. GitHub Actions가 프리뷰 사이트 생성
3. PR 댓글에 미리보기 링크 자동 추가

🎯 성능 최적화 팁

1. 빌드 최적화

{
  "scripts": {
    "build": "docusaurus build --bundleAnalyzer",
    "firebase:deploy": "npm run build && firebase deploy",
    "firebase:serve": "npm run build && firebase serve"
  }
}

2. 캐시 전략

• 변경되지 않는 파일: 최대 캐시 기간 설정
• 자주 변경되는 파일: 짧은 캐시 기간 설정
• Service Worker: 오프라인 지원 추가 고려

3. 보안 헤더 추가

{
  "hosting": {
    "headers": [
      {
        "source": "**",
        "headers": [
          {
            "key": "X-Content-Type-Options",
            "value": "nosniff"
          },
          {
            "key": "X-Frame-Options",
            "value": "DENY"
          }
        ]
      }
    ]
  }
}

🔧 트러블슈팅

자주 발생하는 문제들

1. 빌드 실패

# 로컬에서 빌드 테스트
npm run build

# 의존성 재설치
rm -rf node_modules package-lock.json
npm install

2. Firebase 인증 오류

# 다시 로그인
npx firebase logout
npx firebase login

3. GitHub Actions 권한 오류

• Secrets가 올바르게 설정되었는지 확인
• Environment 설정이 올바른지 확인

📈 모니터링 및 분석

Firebase Analytics 연동

// docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-google-gtag',
      {
        trackingID: 'G-XXXXXXXXXX',
        anonymizeIP: true,
      },
    ],
  ],
};

성능 모니터링

Firebase Console의 Performance 탭에서 다음을 확인할 수 있습니다:

• 페이지 로딩 시간
• 네트워크 요청 분석
• 사용자 경험 메트릭

🎉 결론

Firebase Hosting과 GitHub Actions를 조합하면 다음과 같은 완전한 배포 환경을 구축할 수 있습니다:

✅ 자동화된 배포: 코드 푸시 시 자동 배포
✅ 품질 보장: 타입 체크 및 린팅 자동화
✅ 프리뷰 배포: PR별 미리보기 사이트
✅ 성능 최적화: CDN과 캐싱 전략
✅ 보안: HTTPS 및 보안 헤더 자동 적용

이제 코드 작성에만 집중하고, 배포는 자동화된 시스템에 맡겨보세요!

궁금한 점이나 문제가 발생했다면 댓글로 알려주시기 바랍니다. 🚀

---

참고 자료:

• Firebase Hosting 공식 문서
• GitHub Actions 공식 문서
• Docusaurus 배포 가이드