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

# 배포 아키텍처, 로컬 개발, CLI 배포

> 이 문서는 **[Databricks Apps](/blog/guides/apps/overview)** 섹션의 일부입니다.

***

## 배포 아키텍처: 코드에서 실행까지

Databricks Apps의 배포 과정을 이해하면 배포 실패 시 문제를 빠르게 진단할 수 있습니다. 배포는 크게 **5단계** 로 진행됩니다.

| 단계             | 동작                               | 소요 시간   | 실패 시 증상                        |
| -------------- | -------------------------------- | ------- | ------------------------------ |
| 1. **소스 업로드**  | 로컬 파일이 Databricks 컨트롤 플레인으로 전송   | 수 초     | "파일 크기 초과" 에러 (개별 10MB 제한)     |
| 2. **의존성 설치**  | `requirements.txt` 기반 패키지 설치     | 1\~5분   | `ModuleNotFoundError`, 빌드 타임아웃 |
| 3. **컨테이너 시작** | `app.yaml`의 `command`로 앱 프로세스 시작 | 수 초     | `command` 오류, 포트 바인딩 실패        |
| 4. **헬스체크**    | 지정된 포트에서 HTTP 응답 확인              | 30초\~2분 | 앱이 포트에 바인딩하지 않음, Crash         |
| 5. **URL 라우팅** | 리버스 프록시에 앱 URL 등록                | 수 초     | 내부 라우팅 오류 (드물게 발생)             |

> **참고**
> **배포 시간의 핵심**: 전체 배포 시간의 대부분은 **2단계(의존성 설치)** 에서 소요됩니다. `torch`, `tensorflow` 같은 대용량 패키지가 있으면 10분 이상 걸릴 수 있습니다. 이미 설치된 패키지가 동일하면 캐시가 활용되어 재배포 시간이 크게 단축됩니다. `requirements.txt`에서 버전을 고정하면 캐시 적중률이 높아져 배포 속도가 빨라집니다.

### 배포 전략: Databricks Apps는 어떻게 배포하는가?

Databricks Apps는 **롤링 업데이트(Rolling Update)** 방식을 사용합니다. 새 버전의 컨테이너가 시작되어 헬스체크를 통과하면, 이전 버전의 컨테이너가 종료됩니다.

| 배포 전략        | Databricks Apps 지원 | 설명                               |
| ------------ | ------------------ | -------------------------------- |
| **롤링 업데이트**  | 기본 동작              | 새 버전이 준비되면 이전 버전 교체. 짧은 전환 시간 발생 |
| **블루-그린 배포** | 수동 구현 가능           | 별도 앱(v2)을 만들어 테스트 후 전환. 롤백이 빠름   |
| **카나리 배포**   | 지원하지 않음            | 일부 트래픽만 새 버전으로 보내는 것은 불가         |

> **주의**
> **배포 중 다운타임**: 롤링 업데이트 중에 짧은 시간(수 초\~수십 초) 동안 앱 접속이 불안정할 수 있습니다. 프로덕션 앱에서 무중단 배포가 필요하면, 별도 앱으로 블루-그린 배포를 수동으로 구성하는 것을 권장합니다.

***

## 전체 흐름

```
[로컬 개발] → [로컬 테스트] → [워크스페이스 배포] → [설정/리소스 연결] → [운영]
```

이 흐름의 각 단계는 독립적인 목적을 가지고 있습니다. **로컬 개발** 에서는 빠른 반복으로 코드를 작성하고, **로컬 테스트** 에서는 Databricks 인증과 리소스 접근이 정상적인지 검증하며, **워크스페이스 배포** 에서는 실제 환경에 앱을 올리고, **운영** 에서는 모니터링과 유지보수를 수행합니다.

***

## 1. 로컬 개발 환경 설정

### 필수 도구 설치

```bash theme={null}
# Databricks CLI 설치
pip install databricks-cli
# 또는
brew install databricks
```

이 명령은 Databricks CLI를 설치합니다. CLI는 앱 생성, 배포, 상태 확인, 로그 조회 등 모든 배포 작업을 커맨드라인에서 수행할 수 있게 합니다.

```bash theme={null}
# 인증 설정 (OAuth 기반 — 권장)
databricks auth login --host https://<workspace-url>
```

이 명령은 브라우저 기반 OAuth 인증을 시작합니다. PAT(Personal Access Token)보다 OAuth가 권장되는 이유는 토큰 자동 갱신이 지원되고, 토큰이 파일에 평문으로 저장되지 않기 때문입니다.

```bash theme={null}
# 인증 확인
databricks current-user me
```

이 명령으로 인증이 정상적으로 설정되었는지 확인합니다. 현재 로그인한 사용자 정보가 반환되면 인증이 올바르게 구성된 것입니다.

### 프로젝트 구조

선호하는 IDE(VS Code, PyCharm, IntelliJ 등)에서 개발합니다. Databricks VS Code Extension 사용을 권장합니다.

```bash theme={null}
my-app/
├── app.py              # 앱 코드
├── app.yaml            # 앱 설정 (런타임, 리소스, 환경 변수)
├── requirements.txt    # Python 의존성
└── static/             # 정적 파일 (선택)
```

이 4개 파일이 Databricks App의 전체입니다. `app.py`가 비즈니스 로직, `app.yaml`이 실행 환경, `requirements.txt`가 의존성, `static/`이 정적 에셋입니다.

### app.yaml 예시

```yaml theme={null}
command:
  - "streamlit"
  - "run"
  - "app.py"
  - "--server.port"
  - "$DATABRICKS_APP_PORT"

env:
  - name: "ENVIRONMENT"
    value: "production"

resources:
  - name: "sql-warehouse"
    sql_warehouse:
      id: "abc123def456"
      permission: "CAN_USE"
  - name: "serving-endpoint"
    serving_endpoint:
      name: "my-model-endpoint"
      permission: "CAN_QUERY"
```

이 예시는 Streamlit 앱의 전형적인 설정입니다. `command`로 Streamlit을 시작하고, `env`로 환경 정보를 주입하며, `resources`로 SQL Warehouse와 Serving Endpoint에 대한 접근을 선언합니다.

***

## 2. 로컬 테스트

로컬 테스트는 **배포 전 반드시 거쳐야 할 단계** 입니다. 배포 후 오류를 발견하면 코드 수정 후 재배포 후 대기(2\~5분)의 사이클을 반복해야 하지만, 로컬에서는 즉시 확인할 수 있습니다.

```bash theme={null}
# Databricks CLI 로컬 실행 (권장 — Databricks 인증, 환경 변수 자동 처리)
databricks apps run-local --prepare-environment --debug
```

`--prepare-environment`는 `app.yaml`에 정의된 모든 환경변수와 리소스 참조를 로컬 환경에 자동으로 설정합니다. `--debug`는 상세 로그를 출력하여 인증 문제나 리소스 접근 오류를 즉시 확인할 수 있게 합니다.

또는 프레임워크별로 직접 실행:

```bash theme={null}
# Streamlit
streamlit run app.py

# Flask
gunicorn app:app -w 4

# FastAPI
uvicorn app:app --reload

# Gradio
python app.py
```

직접 실행할 때는 `DATABRICKS_WAREHOUSE_ID`, `DATABRICKS_HOST` 등의 환경변수를 수동으로 설정해야 합니다.

> **참고**
> **`run-local` vs 직접 실행**: `databricks apps run-local`은 `app.yaml`에 정의된 환경 변수와 리소스를 자동으로 주입합니다. 직접 실행 시에는 환경 변수를 수동으로 설정해야 합니다.

> **주의**
> **로컬 테스트의 한계**: 로컬에서는 Databricks의 리버스 프록시, SSL 종료, 포트 매핑 등이 없으므로, 네트워크 관련 문제는 로컬에서 재현되지 않을 수 있습니다. 코드 로직, 데이터 접근, 인증 문제는 로컬에서 검증하고, 네트워크 관련 문제는 배포 후 확인하세요.

***

## 3. Databricks CLI deploy 명령어

### 기본 배포

```bash theme={null}
# 로컬 소스 코드를 워크스페이스에 배포
databricks apps deploy <app-name> --source-code-path /path/to/local/app
```

이 명령은 지정된 디렉토리의 모든 파일을 패키징하여 Databricks에 업로드하고, 컨테이너 빌드와 앱 실행을 트리거합니다. 10MB를 초과하는 개별 파일이 있으면 배포가 실패합니다.

### 배포 상태 확인

```bash theme={null}
# 배포 상태 조회
databricks apps get <app-name>

# 배포 로그 확인 (디버깅 시)
databricks apps logs <app-name>
```

`get` 명령은 앱의 현재 상태, URL, 서비스 프린시펄 정보, 마지막 배포 시간을 반환합니다. `logs` 명령은 Python의 `print()` 출력, 프레임워크의 로그 메시지, 에러 트레이스백을 보여줍니다.

### 앱 중지/재시작

```bash theme={null}
# 앱 중지
databricks apps stop <app-name>

# 앱 시작
databricks apps start <app-name>
```

앱을 중지하면 과금이 중지됩니다. 인메모리 상태는 초기화되므로 영속적 데이터는 미리 저장해야 합니다.