01. 클라우드에 내 집 마련하기 (Setup & Init)
"로컬 환경을 넘어, 전 세계에서 접속 가능한 나만의 시스템 환경을 구축합니다."
이제 내 컴퓨터(localhost)라는 좁은 울타리를 벗어나, 구글의 거대한 인프라(Firebase) 위에 우리만의 AI 시스템을 올릴 준비를 할 차례입니다.
1. 개발 환경 조성 (Environment Setup)
건물을 짓기 전에 단단한 땅과 도구가 필요하듯, 우리 프로젝트를 지탱할 세 가지 핵심 도구를 설치합니다.
📦 Node.js & Python 설치
우리 시스템은 React(프론트엔드)와 FastAPI(백엔드)라는 두 기둥으로 세워집니다.
- Node.js (v22 이상): 프론트엔드 빌드 및 Firebase 도구 실행을 위해 필요합니다.
- Python (v3.10 이상): AI 로직과 백엔드 서버를 위해 필요합니다. (v3.13 권장)
🔥 Firebase CLI 설치 및 로그인
전 세계 구글 서버에 내 코드를 전송할 '배달 트럭'을 설치합니다. 터미널(Terminal)을 열고 아래 명령어를 입력하세요.
# 1. Firebase 도구 설치
npm install -g firebase-tools
# 2. 구글 계정으로 로그인 (웹 브라우저가 열리면 로그인하세요)
firebase login
2. GitHub 저장소 연동 (GitHub Setup)
Firebase 프로젝트와 GitHub를 연결하면, 코드를 push할 때마다 자동으로 배포되는 CI/CD 파이프라인을 구축할 수 있습니다.
🔗 저장소 생성 및 초기 Push
- VS Code에서
course-registration폴더를 생성하고 엽니다. README.md,docs/prd.md파일을 생성하고 내용을 작성합니다.- GitHub에서 새 저장소(Repository)를 생성합니다.
- 아래 명령어로 로컬 프로젝트를 GitHub에 연결하고 초기 코드를 push합니다.
# 1. Git 초기화
git init
git add .
git commit -m "Initial commit: README & PRD"
# 2. GitHub 원격 저장소 연결 (본인 저장소 URL로 변경)
git remote add origin https://github.com/YOUR_USERNAME/course-registration.git
# 3. Main 브랜치로 Push
git branch -M main
git push -u origin main
팁
이 단계를 먼저 완료해야 firebase init 과정에서 GitHub Action 자동 배포 설정 시 해당 저장소를 연동할 수 있습니다.
3. Firebase 콘솔 사전 준비 (Console Setup)
터미널에서 명령어를 입력하기 전에, Firebase Console에서 프로젝트의 뼈대를 먼저 만들어야 합니다.
1️⃣ 프로젝트 생성
- 프로젝트 추가 버튼을 클릭하고 이름을 입력합니다. (예:
course-registration) - Google Analytics는 사용 안 함으로 설정해도 무방합니다.
2️⃣ 요금제 업그레이드 (필수!)
- 좌측 하단 Spark 요금제를 클릭하여 Blaze (종량제)로 변경합니다.
- Why? 우리가 사용할 Cloud Functions(백엔드)는 Blaze 요금제에서만 작동합니다. 걱정 마세요! 개인 학습용으로는 무료 할당량이 충분하여 비용이 거의 발생하지 않습니다.
3️⃣ Firestore 데이터베이스 생성
- 좌측 메뉴 빌드 > Firestore Database 클릭.
- 데이터베이스 만들기 버튼 클릭.
- 위치(Location) 설정:
asia-northeast3(서울) 선택. (매우 중요! 속도 차이가 큽니다) - 보안 규칙: 테스트 모드로 시작.
4. 프로젝트 초기화 (Project Init)
이제 프로젝트 폴더를 만들고, Firebase의 기능들(Hosting, Functions, Firestore)을 이 폴더에 심어보겠습니다.
🏗️ 폴더 생성 및 초기화
# 1. 프로젝트 폴더 생성 및 이동
mkdir course-registration
cd course-registration
# 2. Firebase 초기화 시작
firebase init
Firebase Init 설정 가이드 (실습용)
firebase init을 입력하면 화살표 키와 스페이스바를 이용해 설정을 선택해야 합니다. 아래 순서대로 진행하세요. 중간에 에러가 나는 경우에는 우선 다시 실행해보세요. 또 에러가 나면 에러 메시지를 복사해서 AI에게 물어보세요.
- Which Firebase features...?
- 선택: Firestore, Functions, Hosting (스페이스바로 체크 후 Enter)
- Project Setup
- 선택: Use an existing project → 방금 콘솔에서 만든 프로젝트 선택
- Firestore Setup
- What file should be used for Firestore Rules? → Enter (기본값:
firestore.rules) - What file should be used for Firestore indexes? → Enter (기본값:
firestore.indexes.json)
- What file should be used for Firestore Rules? → Enter (기본값:
- Functions Setup
- Language: Python 선택
- Do you want to install dependencies with pip now? → Yes
- Hosting Setup
- Public directory:
frontend/dist - Configure as a single-page app? → Yes
- Set up automatic builds and deploys with GitHub? → Yes
- Public directory:
- GitHub Actions Setup (위에서 Yes 선택 시 자동 진행)
- For which GitHub repository? →
YOUR_USERNAME/course-registration(본인 저장소 입력) - Set up the workflow to run a build script before every deploy? → Yes
- What script should be run before every deploy? →
npm ci && npm run build - Set up automatic deployment to your site's live channel when a PR is merged? → Yes
- What is the name of the GitHub branch associated with your site's live channel? →
main
- For which GitHub repository? →
⚠️ 매우 중요: GitHub Actions 경로 수정
firebase init이 생성한 GitHub Actions 설정 파일(.github/workflows/*.yml)은 기본적으로 프로젝트 최상위 폴더에서 빌드 명령을 실행합니다. 하지만 우리의 React 앱은 frontend/ 폴더 안에 있죠?
따라서 생성된 .yml 파일을 열어 반드시 경로를 수정해야 합니다. 그렇지 않으면 첫 배포가 실패합니다!
.github/workflows/firebase-hosting-merge.yml:
# 수정 전
- run: npm ci && npm run build
# 수정 후 (cd frontend 추가)
- run: cd frontend && npm ci && npm run build
.github/workflows/firebase-hosting-pull-request.yml:
# 수정 전
- run: npm ci && npm run build
# 수정 후 (cd frontend 추가)
- run: cd frontend && npm ci && npm run build
💡 이 수정을 하지 않으면 GitHub Actions 배포 시
package-lock.json not found에러가 발생합니다.
🔨 프론트엔드 골격 만들기 (Frontend Skeleton)
firebase init으로 호스팅 설정을 마쳤지만, 아직 frontend 폴더에는 React 앱이 없습니다. 빈 껍데기만 있으면 배포 시 에러가 나므로, 지금 바로 Vite 리액트 앱을 생성합니다.
# 루트 폴더에서 실행
npm create vite@latest frontend -- --template react-ts
# 경고: "Target directory is not empty"가 나오면?
# -> "Remove existing files and continue"를 선택하세요.
# (firebase init이 만든 임시 index.html을 삭제하는 것입니다)
# 필요시 의존성 설치
# cd frontend
# npm install
# cd ..
5. 프로젝트 공생 구조 설계 (Architecture)
우리 프로젝트는 하나의 뿌리(Root)에서 두 개의 줄기(Frontend, Backend)가 뻗어 나가는 구조를 가집니다.
📂 폴더 구조 미리보기
초기화가 완료되면 폴더 구조가 다음과 같이 잡혀야 합니다.
firebase.json: 전체 시스템의 설계도 (어떤 문으로 들어오면 어디로 보낼지 결정)functions/: 백엔드(Python) 코드가 살게 될 곳frontend/: 프론트엔드(React) 코드가 살게 될 곳 (추후npm create vite로 생성)
graph TD
Root["📁 course-registration (Root)"]
Root --> Func["📁 functions (Python/FastAPI)"]
Root --> Front["📁 frontend (React/TS)"]
Root --> Config["📄 firebase.json"]
6. [Check] 에뮬레이터 UI 접속 확인
Firebase는 실제 서버에 올리기 전, 내 컴퓨터에 '가짜 클라우드 환경'을 만들어주는 에뮬레이터(Emulator)를 제공합니다. 에뮬레이터는 frontend/dist 폴더를 웹 서버처럼 서비스하고, functions/ 폴더의 파이썬 코드를 서버리스 함수처럼 실행합니다. 에뮬레이터를 실행하기 전에 frontend 폴더에서 npm run build를 실행하여 frontend/dist 폴더를 생성해야 합니다.
필수: Java 설치 (에뮬레이터 실행 조건)
Firebase 에뮬레이터를 실행하려면 컴퓨터에 Java (JDK 11 이상)가 설치되어 있어야 합니다.
먼저 터미널에 java -version을 입력해보세요. 버전 정보가 잘 나오면 설치할 필요 없습니다!
- Mac 사용자 (없을 경우):
- Windows 사용자 (없을 경우): MSI 설치 (권장)
Microsoft Build of OpenJDK에서 .msi 파일을 다운로드하여 설치하세요.
환경 변수(
JAVA_HOME)를 자동으로 설정해주어 훨씬 편리합니다.
에뮬레이터 실행
확인 방법
- 터미널에 뜬
Emulator UI주소(보통http://127.0.0.1:4000)를 클릭합니다. - 화면에 Firestore, Authentication 등의 메뉴가 보이면 내 컴퓨터 안에 작은 구글 서버가 성공적으로 차려진 것입니다! 🎉
중요 개념: 포트(Port)와 번호들 (Firebase Edition)
우리의 컴퓨터라는 건물 안에 Firebase 친구들이 각각의 호수(Port)를 잡고 입주했습니다.
- 5001호: Functions (백엔드 API 서버)
- 5002호: Hosting (프론트엔드 화면 서버)
- 8080호: Firestore (데이터베이스)
- 9099호: Auth (로그인 관리소)
- 4000호: Emulator UI (이 모든 걸 관리하는 관리 사무소)
이 번호들이 서로 다르기 때문에 우리가 한 컴퓨터에서 백엔드와 프론트엔드를 동시에 개발할 수 있는 것입니다!
7. Git 전략 세우기 (Branch Strategy)
배포는 짜릿하지만 위험합니다. 실수로 완성되지 않은 코드를 전 세계에 뿌리지 않도록 '완충 지대'를 만듭니다.
- main 브랜치: 실제 서비스가 돌아가는 곳 (건드리지 마세요! 오직 배포용)
- develop 브랜치: 우리가 신나게 개발하고 실험하는 곳
📝 .gitignore 보강
.gitignore 파일이 root 폴더를 비롯하여 frontend, functions 폴더에 모두 생성되어 있을 것입니다. AI를 이용하여 .gitignore 파일 내용을 보강하도록 합니다.
루트 폴더에 .gitignore를 생성하여 민감한 정보를 반드시 차단합니다 (.env 등).
AI 프롬프트 예시
.gitignore 파일들을 보강해줘. functions/ 폴더에는 Python 백엔드가 있고, frontend/ 폴더에는 React 앱이 있어. 루트, functions/, frontend/ 각각의 .gitignore에 추가해야 할 표준적인 무시 파일 목록을 알려줘. (예: .env, node_modules, venv, pycache, .DS_Store 등)
🚀 커밋 및 브랜치 생성
# 1. 변경사항 커밋 및 Main 브랜치 Push
git add .
git commit -m "Setup: Firebase Init & Project Structure"
git push origin main
# 2. Develop 브랜치 생성 및 이동
git checkout -b develop
git push -u origin develop
8. 자동 배포 확인
이제 GitHub Actions가 정상적으로 세팅되었는지 확인하기 위해 첫 배포를 진행해 봅시다.
- Pull Request 생성: GitHub 저장소 페이지에서
develop→main브랜치로 향하는 Pull Request(PR)를 생성합니다. - CI/CD 체크: PR 생성 직후 Actions 탭에 노란색 점(Pending)이 뜨며 테스트와 빌드가 자동으로 시작되는지 확인합니다.
- 만약 빨간색 X(Fail)가 뜬다면, 로그를 확인하여 에러를 수정하고 다시 Push 해야 합니다.
- Merge & 배포: 모든 체크가 통과하면(초록색 체크 ✅), Merge Pull Request 버튼을 눌러 병합합니다.
- 최종 확인: Merge가 완료되면
main브랜치에 코드가 푸시되면서 Firebase Hosting에 자동 배포가 시작됩니다.- 잠시 후 Firebase Console > Hosting 탭에 접속하여 "배포 완료" 상태를 확인하세요.
- 화면에 표시된 도메인(예:
https://your-project.web.app)을 클릭하면, 방금 로컬 에뮬레이터에서 본 것과 똑같은 웹사이트가 전 세계에 배포된 것을 볼 수 있습니다! 🌍
팁
이후 모든 개발은 develop 브랜치에서 진행하며, 배포 시점에 main 브랜치로 Merge합니다. main 브랜치에 코드가 푸시되면 Firebase Hosting에 자동 배포됩니다.
이 과정은 github 사이트에서 pull request를 통해 진행하는 것이 좋습니다.
프로덕션 개발시: 모든 작업은 feature/* 브랜치에서 하고, 로컬 에뮬레이터에서 완벽하게 검증되었을 때만 develop으로 합칩니다. develop 브랜치에 대해 배포 테스트를 진행해서 완벽해졌을 때만 main으로 합칩니다.
9. 핵심 정리
| 용어 | 설명 | 비유 |
|---|---|---|
| Firebase CLI | 내 코드를 구글 서버로 보내주는 도구 | 택배 기사님 |
| Functions | 클라우드에서 실행되는 파이썬 코드 | 24시간 요리하는 주방 |
| Hosting | 전 세계 누구나 접속할 수 있는 웹 공간 | 가게의 간판과 매대 |
| Emulator | 클라우드 환경을 내 컴퓨터에 복제한 것 | 모델 하우스 |
준비 완료! 이제 우리 집의 기초 공사가 끝났습니다. 다음 02장에서는 이 집에 문지기(Google Login)를 세우고, 실제로 전 세계에서 접속 가능한 첫 번째 URL을 발급받아 보겠습니다! 🚀
학습 가이드
위 설정 중 firebase init 과정에서 에러가 발생했다면 대부분 권한 문제이거나 로그인 세션 만료 때문입니다. firebase logout 후 다시 firebase login을 시도해 보세요!