> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magicmealkits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 설치

> Magic Meal Kits 서버를 여러분의 Google Cloud 프로젝트에 배포하고, 이후 업그레이드하세요.

Magic Meal Kits는 웹 앱 [make.magicmealkits.com](https://make.magicmealkits.com)에서
설치합니다 — 원클릭 위저드가 MMK 이미지를 **여러분의** Google Cloud 프로젝트에
배포합니다. 배포, 데이터, URL 모두 여러분이 소유합니다.

## 사전 준비

<CardGroup cols={3}>
  <Card title="Magic Meal Kits 라이선스" icon="key">
    구독하면 서버가 사용하는 **라이선스 키**와 **API 키**가 제공됩니다.
  </Card>

  <Card title="구글 계정" icon="google">
    Google Cloud에 로그인할 때 쓰는 **동일한** 계정을 사용하세요.
  </Card>

  <Card title="결제가 활성화된 GCP 프로젝트" icon="cloud">
    Cloud Run은 **결제 활성화**가 필요합니다. MMK 자체는 무료이며, 인프라는 Google이
    청구합니다 — 가벼운 사용량은 무료 등급으로 충분합니다.
  </Card>
</CardGroup>

<Warning>
  **Google Workspace 계정이 아니라 일반 Gmail 계정으로 설치하세요.** 배포 위저드는 현재
  **일반 Gmail 계정**의 GCP 환경에만 설치를 지원합니다. (Make 계정과 Make에서 연동하는
  계정은 워크스페이스를 사용하셔도 무방하며, 이 제한은 매직밀키트 설치에만 적용됩니다.)
</Warning>

## 서버 배포

[make.magicmealkits.com/deploy](https://make.magicmealkits.com/deploy)를 열고 위저드를
따라가세요.

<Steps>
  <Step title="Google Cloud 연결">
    **Connect to Google Cloud**를 클릭하고 접근을 허용하세요. 위저드가 프로젝트를 보고
    리소스를 만들 수 있도록 Google Cloud에서 쓰는 **동일한 구글 계정**을 사용하세요.
  </Step>

  <Step title="앱 선택">
    **Magic Meal Kits** 템플릿(요금제에 따라 **Magic Meal Kits Pro**)을 선택하세요.
  </Step>

  <Step title="프로젝트 선택 또는 생성">
    기존 GCP 프로젝트를 선택하거나 **새로 생성**하세요(프로젝트 이름은 6\~30자, 소문자/
    숫자/하이픈, 첫 글자는 문자). 그다음 위저드가 **결제 상태를 확인**하고, 활성화될
    때까지 배포를 막습니다 — Google Cloud 결제 콘솔에서 활성화한 뒤 **Recheck Billing**을
    클릭하세요.
  </Step>

  <Step title="등급 선택 후 배포">
    **리소스 등급**을 선택하고 \*\*Let's Go!\*\*를 클릭하세요.

    | 등급              | 리소스             | 적합한 용도      | 대략적 GCP 비용  |
    | --------------- | --------------- | ----------- | ----------- |
    | **Free**        | 1 vCPU / 256 MB | 개발 및 테스트    | GCP 한도 내 무료 |
    | **Basic**       | 1 vCPU / 512 MB | 프로덕션 워크로드   | 월 \~\$5     |
    | **Performance** | 2 vCPU / 1 GB   | 트래픽 많은 프로덕션 | 월 \~\$15    |

    <Note>
      Magic Meal Kits는 무료로 사용합니다. 인프라 비용은 Google Cloud가 직접 청구하며,
      넉넉한 무료 등급(vCPU-초, 메모리-초, 월 약 200만 요청)이 포함됩니다. 실제 비용은
      사용량과 리전에 따라 달라집니다.
    </Note>
  </Step>

  <Step title="완료">
    성공 화면에서 **Visit Your Application**으로 서버를 열거나, **View Deployment
    Status**로 [App Status](https://make.magicmealkits.com/app-status) 페이지를 여세요.
  </Step>
</Steps>

## 설치되는 것

설치 프로그램이 서버에 필요한 모든 것을 **여러분의 프로젝트에** 프로비저닝합니다.

* **Cloud Run** 서비스 `magic-meal-kits` (리전 `us-west1`)
* **Firestore** `(default)` 데이터베이스 — 작업 및 동기화 상태
* **BigQuery** 데이터셋 `threads_data` — 검색 중심의 게시물/답글 저장소
* **Secret Manager**, **Cloud Tasks**
* 필요한 Google API 및 IAM 역할, 그리고 공개(호출 가능) URL

서비스에 다음 환경 변수도 설정됩니다.

| 변수                     | 용도           |
| ---------------------- | ------------ |
| `GOOGLE_CLOUD_PROJECT` | 프로젝트 ID      |
| `MMK_LICENSE_KEY`      | 라이선스 키       |
| `MMK_API_KEY`          | 요청 인증용 API 키 |
| `APP_TYPE`             | 애플리케이션 유형    |

## 배포 후

**서버 URL**과 **API 키**는 [App Status](https://make.magicmealkits.com/app-status)
페이지에 표시됩니다 — 거기서 복사하세요(직접 구성하는 값이 아닙니다).

<CardGroup cols={2}>
  <Card title="인증" icon="key" href="/ko/authentication">
    `X-API-KEY` 헤더와 라이선스 등급 동작.
  </Card>

  <Card title="빠른 시작" icon="rocket" href="/ko/quickstart">
    배포에 첫 요청을 보내 보세요.
  </Card>
</CardGroup>

## 업그레이드(재배포)

배포를 최신 서버 버전으로 올리려면
[App Status](https://make.magicmealkits.com/app-status)를 열고 **Service Management**
아래의 \*\*Update Service (Redeploy)\*\*를 클릭하세요. 이 페이지에는 현재 **버전**과 **마지막
배포** 시각이 표시됩니다. 재배포는 **인플레이스 업그레이드**입니다 — 실행 중인 컨테이너를
최신 버전으로 교체하고 새 Cloud Run 리비전을 만듭니다.

| 유지됨                          | 변경됨                |
| ---------------------------- | ------------------ |
| 서버 URL, API 키, 라이선스          | 컨테이너 **이미지 / 버전**  |
| GCP 프로젝트 및 리전                | 새 Cloud Run 리비전 생성 |
| **Firestore & BigQuery 데이터** | —                  |
| 환경 변수 / 설정                   | —                  |

<Note>
  재배포해도 데이터는 **사라지지 않고**, URL과 API 키도 **바뀌지 않습니다** — 서버 버전만
  올라갑니다. 자동 "업데이트 알림" 배너는 없으며, 원할 때 App Status에서 직접
  업그레이드를 실행합니다.
</Note>