Quickstart script for Chat UI template

[simonfaltum]

Summary

Added convenience scripts to streamline the initial setup and daily development workflow for the Databricks Chatbot template.

New Scripts

1. scripts/quickstart.sh - Automated First-Time Setup

A comprehensive, linear setup script that guides users through the complete initial configuration. In an ideal scenario (full setup with database and deployment), the
script performs these steps:

1. Prerequisites Installation

• Automatically installs required tools: jq (JSON parsing), nvm (Node Version Manager), and Databricks CLI
• Uses Homebrew on macOS, or falls back to curl-based installation
• Sets up Node.js 20 and activates it for the project

2. Configuration Files Setup

• Creates .env.local from .env.example (if not already present)
• Preserves existing configuration if .env.local already exists

3. Databricks Authentication

• Detects existing Databricks CLI profiles
• Allows selection from existing profiles or interactive login for new workspaces
• Validates the selected profile by testing authentication
• Re-authenticates expired profiles automatically
• Saves the profile name to .env.local (e.g., DATABRICKS_CONFIG_PROFILE=default)

4. Application Configuration

• Serving Endpoint:
  • Prompts for the AI Model Serving Endpoint name (e.g., databricks-gpt-4-turbo)
  • Validates that the endpoint exists in your workspace
  • Lists available endpoints if the specified one is not found
  • Updates both databricks.yml and .env.local with the endpoint name
• Database Setup (Optional):
  • Asks whether to enable persistent chat history
  • If yes: Uncomments database configuration sections in databricks.yml
  • If no: Ensures database sections are commented out (ephemeral mode)
• Dependencies:
  • Runs npm install to set up project dependencies

5. Deployment & Database Provisioning

• Deployment (Optional):
  • Prompts whether to deploy resources to Databricks now
  • If yes: Runs databricks bundle deploy -t dev
  • Database provisioning takes 5-10 minutes on first deployment
• Database Connection Discovery:
  • If database is enabled and deployment occurred:
    • Calculates the database instance name based on your username
    • Polls for database DNS hostname (PGHOST) with 10-minute timeout
    • Automatically writes connection details to .env.local:
      • PGUSER (your Databricks username)
      • PGHOST (database hostname)
      • PGDATABASE=databricks_postgres
      • PGPORT=5432
    • Runs npm run db:migrate to set up the database schema

Additional Features:

• App Name Validation: Checks that the generated app name is ≤30 characters (Databricks Apps requirement)
• Endpoint Validation: Soft-check to verify the serving endpoint exists before proceeding
• Smart Configuration: Preserves existing configuration when re-running the script
• Helpful Warnings: Notifies users about deployment costs and manual cleanup needs

Result: After the ideal flow completes, you have:

• Fully configured local environment (.env.local)
• Optionally: Deployed backend with provisioned database
• Database schema migrations applied (if database enabled)
• Ready to run npm run dev with full functionality

2. scripts/start-app.sh - Quick App Startup

A simple convenience script for daily development:

• Runs npm install to ensure dependencies are up-to-date
• Starts the development server with npm run dev
• Displays helpful URLs for frontend (http://localhost:3000) and backend (http://localhost:3001)

Files Changed

• scripts/quickstart.sh - New comprehensive setup script (542 lines)
• scripts/start-app.sh - New startup convenience script (23 lines)
• README.md - Updated to feature these scripts as the recommended setup method
• server/src/index.ts - Clarified backend server port in console output

Testing

Please test the following scenarios:

Scenario 1: Entirely Local (No Database, No Deployment)

1. Run ./scripts/quickstart.sh
2. Select No when asked about database
3. Select No when asked about deployment
4. Expected Result:
   • .env.local contains DATABRICKS_CONFIG_PROFILE and DATABRICKS_SERVING_ENDPOINT
   • No database environment variables in .env.local
   • App runs in ephemeral mode with npm run dev
   • Sidebar shows "No chat history available"

Scenario 2: Local with Existing Database

1. Ensure database was previously deployed (databricks bundle deploy with database enabled)
2. Run ./scripts/quickstart.sh
3. Select Yes when asked about database
4. Select No when asked about deployment
5. Expected Result:
   • Script finds existing database instance
   • Writes PGHOST to .env.local (along with PGUSER, PGDATABASE, PGPORT)
   • Runs migrations successfully
   • App runs with persistent chat history

Scenario 3: Full Deploy (First-Time Setup)

1. Run ./scripts/quickstart.sh on a clean install
2. Select Yes when asked about database
3. Select Yes when asked about deployment
4. Expected Result:
   • Script deploys bundle (takes 5-10 minutes for database provisioning)
   • Polls for database hostname (PGHOST) until available
   • Writes complete database configuration to .env.local
   • Runs migrations automatically
   • App is ready to start with npm run dev or ./scripts/start-app.sh

Additional Test Cases

• Invalid Serving Endpoint: Enter a non-existent endpoint name
  • Script should warn and list available endpoints
  • Ask for confirmation before proceeding
• App Name Too Long: Test with a Databricks username that would generate a >30 character app name
  • Script should error with clear message about modifying databricks.yml
• Re-running Script: Run the script multiple times
  • Should preserve existing configuration
  • Should allow changing database configuration (enable → disable or vice versa)
• Expired Authentication: Test with an expired Databricks profile
  • Script should detect failed authentication and prompt for re-login

Benefits

1. Faster onboarding: New users can get started in minutes instead of following many manual steps
2. Fewer errors: Automated validation prevents common configuration mistakes
3. Better DX: Clear prompts and helpful error messages guide users through setup
4. Flexible: Supports multiple workflows (local-only, with existing DB, full deploy)
5. Idempotent: Safe to re-run the script to update configuration

[bbqiu]

from running through this myself, a few nits:

1. when i selected "y" for customizing the name, the script did not wait for my input
2. script did not wait for me to select an option when deploying the app to databricks
3. can we change the default to not be gpt-5-1 if it doesn't work right now (tracked in https://databricks.atlassian.net/browse/ML-59783)

[simonfaltum]

from running through this myself, a few nits:

1. when i selected "y" for customizing the name, the script did not wait for my input
2. script did not wait for me to select an option when deploying the app to databricks
3. can we change the default to not be gpt-5-1 if it doesn't work right now (tracked in https://databricks.atlassian.net/browse/ML-59783)

I couldn't reproduce but I have done some more testing and made the customizing name more robust.
I don't think there is any "option" when deploying the app to databricks?
I have changed to claude 4 sonnet as default.

I also only tried this with zsh but it should work across macOS and linux

[bbqiu]

ah going through this again, if you type any letters other than y or n, the script treats it as a yes (don't have to be "y" or "n", it'll proceed to the next steps). if we fix this, i think this looks great!

[bbqiu]

from a quick runthrough again, i think the same behavior is still present:

claude suggested something like this to require the user to specifically type "y" or "n":

while true; do
      read -p "Enable database? (y/N): " -n 1 -r
      echo
      case $REPLY in
          [Yy]) USE_DATABASE=true; break ;;
          [Nn]|"") USE_DATABASE=false; break ;;
          *) echo "❌ Please enter 'y' or 'n'" ;;
      esac
  done

[simonfaltum]

I can't reproduce it?

Screen.Recording.2025-11-27.at.16.05.00.mov

[eLysgaard]

Can you add an entry in CLAUDE.md that mentions, suggests, and instructs claude how to this script?

[simonfaltum]

jenkins merge