Skip to main content
이 가이드는 AI Dev Kit Builder App을 Databricks Workspace에 배포하는 전체 절차를 다룹니다.

​
배포 아키텍처 이해

Builder App을 Databricks Apps에 배포하면, 다음과 같은 아키텍처로 운영됩니다: 
사용자 브라우저
     │
     ▼
Databricks Apps (서버리스 컨테이너)
  ├─ FastAPI + 빌드된 React (정적 파일)
  ├─ Claude Agent SDK + MCP Server (내장)
  └─ Lakebase 연결 (대화 이력 영구 저장)
     │
     ▼
Databricks Workspace APIs
  ├─ SQL Warehouse
  ├─ Clusters
  ├─ Unity Catalog
  └─ ... (30+ 서비스)

​
로컬 개발 vs Databricks Apps 배포 비교

항목로컬 개발Databricks Apps
인증DATABRICKS_TOKEN 직접 설정X-Forwarded-Access-Token 자동 전달
LLMAnthropic API Key 필요Databricks FMAPI 사용 가능 (키 불필요)
접근 범위개인만 사용팀 전체 접근 가능
영속성로컬 파일 시스템Lakebase 영구 저장
스케일링단일 프로세스Databricks Apps 자동 관리
URLlocalhost:3000<app-name>-<workspace-id>.aws.databricksapps.com

​
CI/CD 통합

프로덕션 환경에서는 배포를 자동화하는 것이 좋습니다. GitHub Actions를 활용한 CI/CD 파이프라인 예시: 
# .github/workflows/deploy.yml
name: Deploy Builder App
on:
  push:
    branches: [main]
    paths: ['databricks-builder-app/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: databricks/setup-cli@main
      - name: Build Frontend
        run: cd databricks-builder-app/client && npm install && npm run build
      - name: Deploy to Databricks Apps
        run: cd databricks-builder-app && bash scripts/deploy.sh ${{ vars.APP_NAME }}
        env:
          DATABRICKS_HOST: ${{ secrets.DATABRICKS_HOST }}
          DATABRICKS_TOKEN: ${{ secrets.DATABRICKS_TOKEN }}
팁 CI/CD 파이프라인을 사용하면 코드 변경 시 자동으로 테스트 → 빌드 → 배포가 수행됩니다. main 브랜치에 머지하면 프로덕션 환경에 자동 배포되는 GitOps 패턴을 구현할 수 있습니다.

​
사전 요구사항

항목필수 여부설명
Databricks Workspace필수Premium 이상, Apps 기능 활성화
Databricks CLI필수v0.278.0 이상 (databricks --version)
Node.js필수v18+ (프론트엔드 빌드용)
Git필수소스코드 clone
Lakebase선택대화 기록 영구 저장 (없으면 메모리 저장)

​
Step 1: 소스코드 준비

git clone https://github.com/databricks-solutions/ai-dev-kit.git
cd ai-dev-kit/databricks-builder-app

​
Step 2: Databricks CLI 인증

databricks auth login --host https://<workspace-url>.cloud.databricks.com
브라우저에서 SSO 인증을 완료합니다.

​
Step 3: 앱 생성

databricks apps create <app-name>
참고 앱 이름은 소문자, 숫자, 하이픈만 사용 가능합니다. 예: my-builder-app

​
Step 4: app.yaml 설정

app.yaml.example을 복사하여 app.yaml로 만듭니다: 
cp app.yaml.example app.yaml

​
Option A: Lakebase 없이 배포 (간단)

대화 기록이 메모리에만 저장됩니다. 앱 재시작 시 기록이 사라지지만, 빠르게 시작할 수 있습니다. 
command:
  - "uvicorn"
  - "server.app:app"
  - "--host"
  - "0.0.0.0"
  - "--port"
  - "$DATABRICKS_APP_PORT"

env:
  - name: ENV
    value: "production"
  - name: PROJECTS_BASE_DIR
    value: "./projects"
  - name: PYTHONPATH
    value: "/app/python/source_code/packages"
  - name: ENABLED_SKILLS
    value: ""
  - name: SKILLS_ONLY_MODE
    value: "false"

  # LLM - Databricks Foundation Models
  - name: LLM_PROVIDER
    value: "DATABRICKS"
  - name: DATABRICKS_MODEL
    value: "databricks-claude-sonnet-4-6"
  - name: DATABRICKS_MODEL_MINI
    value: "databricks-gpt-5-4-mini"

  - name: CLAUDE_CODE_STREAM_CLOSE_TIMEOUT
    value: "3600000"
  - name: MLFLOW_TRACKING_URI
    value: "databricks"
  - name: AUTO_GRANT_PERMISSIONS_TO
    value: "account users"

​
Option B: Lakebase Autoscale로 배포 (권장)

대화 기록이 PostgreSQL에 영구 저장됩니다. Scale-to-zero로 비용 효율적입니다.
  1. Lakebase 프로젝트 생성: Workspace → Catalog → Lakebase → Create project
  2. Endpoint 이름 확인: Lakebase → 프로젝트 → Branches → Endpoints
env:
  # ... 위 공통 설정 동일 ...

  # Lakebase Autoscale
  - name: LAKEBASE_ENDPOINT
    value: "projects/<project-name>/branches/production/endpoints/<endpoint>"
  - name: LAKEBASE_DATABASE_NAME
    value: "databricks_postgres"
주의 Lakebase Autoscale는 Databricks App의 리소스로 추가할 필요 없이 OAuth로 자동 연결됩니다.

​
Option C: Lakebase Provisioned로 배포

고정 용량 인스턴스를 사용합니다. 리소스로 명시적 추가가 필요합니다. 
databricks apps add-resource <app-name> \
  --resource-type database \
  --resource-name lakebase \
  --database-instance <instance-name>

env:
  # ... 공통 설정 ...

  # Lakebase Provisioned
  - name: LAKEBASE_INSTANCE_NAME
    value: "<instance-name>"
  - name: LAKEBASE_DATABASE_NAME
    value: "databricks_postgres"

​
LLM 모델 선택

옵션설정특징
Databricks FMAPI(기본)LLM_PROVIDER=DATABRICKS별도 API 키 불필요, 워크스페이스 과금
Anthropic 직접ANTHROPIC_API_KEY=sk-ant-...Claude API 키 필요, 별도 과금
Azure OpenAILLM_PROVIDER=AZUREAzure 리소스 필요

​
Step 5: 배포

bash scripts/deploy.sh <app-name>
이 스크립트가 자동으로 수행하는 작업:
  1. Databricks CLI 버전 확인— v0.278.0 이상이 필요합니다. 이전 버전에는 Apps 관련 버그가 있을 수 있습니다.
  2. 프론트엔드 빌드— React 소스를 Webpack으로 번들링하여 client/dist/ 디렉토리에 정적 파일로 생성합니다.
  3. 35개 스킬 다운로드— databricks-skills 레포에서 최신 스킬 파일을 다운로드합니다.
  4. Workspace에 소스코드 업로드— Databricks Workspace Files에 소스코드를 동기화합니다.
  5. 앱 배포 및 시작— Databricks Apps가 컨테이너를 생성하고, uvicorn으로 FastAPI 서버를 시작합니다.
참고 프론트엔드가 이미 빌드되어 있으면 --skip-build 옵션으로 빌드를 건너뛸 수 있습니다: 
bash scripts/deploy.sh <app-name> --skip-build

​
Step 6: 확인

배포 완료 후: 
databricks apps list | grep <app-name>
상태가 ACTIVE + SUCCEEDED이면 성공입니다. 앱 URL: https://<app-name>-<workspace-id>.aws.databricksapps.com

​
트러블슈팅

증상원인해결
Apps 쿼타 초과 (300개)워크스페이스 앱 수 한도STOPPED 앱 삭제 또는 다른 워크스페이스 사용
배포 실패 (FAILED)app.yaml 오류 또는 의존성 문제databricks apps get <app-name> 로 에러 메시지 확인
LLM 응답 없음모델 엔드포인트 비활성databricks serving-endpoints list로 모델 상태 확인
Lakebase 연결 실패Endpoint 이름 오류 또는 권한Lakebase 프로젝트에서 Endpoint 이름 재확인
빌드 시 npm 오류Node.js 버전 불일치node --version으로 v18+ 확인, nvm use 18
앱 시작 후 502 에러앱 초기화 중2~3분 후 재시도, 로그에서 에러 확인
MCP 도구 로드 실패스킬 파일 누락deploy.sh가 스킬 다운로드를 포함하는지 확인

​
상세 디버깅

배포 문제가 발생하면 다음 명령으로 상세 로그를 확인합니다: 
# 앱 상태 확인
databricks apps get <app-name>

# 앱 로그 확인 (최근 100줄)
databricks apps get-logs <app-name> --num-lines 100

# 앱 재배포 (설정 변경 후)
databricks apps deploy <app-name> --source-code-path .

​
배포 후 운영 가이드

​
업데이트 배포

코드나 설정을 변경한 후 재배포하려면: 
# 프론트엔드 변경 시: 빌드 후 배포
cd client && npm run build && cd ..
bash scripts/deploy.sh <app-name>

# 백엔드만 변경 시: 빌드 건너뛰기
bash scripts/deploy.sh <app-name> --skip-build

​
앱 관리 명령

명령설명
databricks apps list전체 앱 목록 조회
databricks apps get <name>앱 상태 상세 조회
databricks apps stop <name>앱 중지 (비용 절약)
databricks apps start <name>중지된 앱 재시작
databricks apps delete <name>앱 완전 삭제
팁 사용하지 않는 앱은 stop으로 중지하여 비용을 절약할 수 있습니다. 중지된 앱은 URL에 접근할 수 없지만, 설정과 데이터는 유지됩니다. start로 언제든 재시작할 수 있습니다.

​
참고