website/docs/deployment/quickstart-databricks.md

metadata

sidebar_position: 3

Quick Start Guide - React + FastAPI Databricks App

🚀 Deploy to Databricks Apps (5 minutes)

Prerequisites

• Databricks workspace with Apps enabled
• OpenAI API key

Steps

# 1. Set environment variables
export DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
export DATABRICKS_TOKEN=dapi1234567890abcdef
export OPENAI_API_KEY=sk-...

# 2. Deploy!
./scripts/deploy-databricks-app.sh

# 3. Access your app
# https://your-workspace.cloud.databricks.com/apps/open-navigator

That's it! 🎉

---

💻 Local Development (10 minutes)

Option A: Hot Reload (Recommended for UI development)

# Terminal 1 - Backend
source venv/bin/activate
uvicorn api.app:app --reload
# http://localhost:8000

# Terminal 2 - Frontend (hot reload!)
cd frontend
npm install
npm run dev
# http://localhost:3000

Option B: Production Mode (Test full build)

# Build frontend
cd frontend
npm install
npm run build
cd ..

# Run app
source venv/bin/activate
python scripts/test-app.py
# http://localhost:8000

---

📁 Project Structure

open-navigator/
├── frontend/                 # React app
│   ├── src/
│   │   ├── pages/           # Dashboard, Heatmap, etc.
│   │   └── components/      # Layout, etc.
│   └── package.json
│
├── api/
│   ├── app.py              # NEW: FastAPI for Databricks App
│   └── main.py             # LEGACY: Original CLI API
│
├── scripts/
│   ├── deploy-databricks-app.sh   # Deploy to cloud
│   ├── setup-local.sh             # Setup dev environment
│   └── test-app.py                # Test production build
│
├── app.yaml                # Databricks App config
└── Dockerfile.app          # Container image

---

🎯 Common Tasks

Deploy to Databricks

./scripts/deploy-databricks-app.sh

View App Logs

databricks apps logs open-navigator --follow

Update Frontend

cd frontend
# Make changes...
npm run build
cd ..
./scripts/deploy-databricks-app.sh

Run Tests

source venv/bin/activate
pytest tests/

Check Agent Status

curl http://localhost:8000/api/agents/status

---

📊 Frontend Pages

Page	Route	Description
Dashboard	/	Stats, charts, recent activity
Heatmap	/heatmap	Interactive map of opportunities
Documents	/documents	Browse analyzed documents
Opportunities	/opportunities	Manage advocacy opportunities
Settings	/settings	Configure system

---

🔧 Configuration

Environment Variables

Variable	Required	Description
DATABRICKS_HOST	Yes	Workspace URL
DATABRICKS_TOKEN	Yes	Access token
OPENAI_API_KEY	Yes	OpenAI API key
DATABRICKS_WAREHOUSE_ID	Yes	SQL warehouse

Databricks Secrets

# Create secrets scope
databricks secrets create-scope --scope oral-health-app

# Add secrets
databricks secrets put --scope oral-health-app --key host --string-value "$DATABRICKS_HOST"
databricks secrets put --scope oral-health-app --key token --string-value "$DATABRICKS_TOKEN"
databricks secrets put --scope oral-health-app --key openai_key --string-value "$OPENAI_API_KEY"

---

🐛 Troubleshooting

"Frontend not built"

cd frontend && npm install && npm run build

"Module not found"

source venv/bin/activate
pip install -r requirements-cpu.txt

"Databricks CLI not found"

pip install databricks-cli

"Can't connect to backend"

Check that backend is running on :8000 and frontend proxies to it.

---

📚 Documentation

• Full Deployment Guide: DATABRICKS_APP_GUIDE.md
• Refactoring Details: REACT_REFACTORING.md
• Agent Bricks Info: databricks/README.md
• Main README: README.md

---

🆘 Need Help?

1. Check logs: databricks apps logs open-navigator
2. Review docs in the /docs folder
3. Open an issue on GitHub

---

⚡ Pro Tips

• Use npm run dev for instant hot reload during UI development
• Deploy often - deployment takes ~2 minutes
• Monitor with databricks apps get open-navigator
• Scale to zero saves costs when idle
• Use Chrome DevTools to debug React components

---

Happy Advocating! 🦷✨