Setup

Prerequisites

Tool	Version
Node.js	v18 or later
npm	Bundled with Node.js
Python	v3.9 or later
pip	Bundled with Python
Databricks service principal	`DATABRICKS_CLIENT_ID` / `DATABRICKS_CLIENT_SECRET` must already be issued

Steps

Mind the working directory

Every command below runs inside nodejs-fastapi-hello-world-app/, not at the repository root. The directory name comes from the Databricks template and has nothing to do with the app's contents.

1. Clone the Repository

git clone https://github.com/fourdigit/databricks-apps-survey-analysis.git
cd databricks-apps-survey-analysis/nodejs-fastapi-hello-world-app

2. Install Dependencies

npm install
pip install -r requirements.txt

A Python virtual environment is recommended.

python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate
pip install -r requirements.txt

databricks-sdk is not in requirements.txt

Table listing (GET /api/catalogs/{catalog}/schemas/{schema}/tables) uses the databricks-sdk WorkspaceClient. The app still starts without it, but that endpoint returns 503 when called. Run pip install databricks-sdk separately if you need it.

3. Configure Environment Variables

DATABRICKS_HOST and DATABRICKS_HTTP_PATH are filled in automatically from databricks.yml / app.yaml, so .env only needs the credentials.

touch .env

Set each entry in .env.

Variable	Description	Example
`DATABRICKS_CLIENT_ID`	Service principal client ID	`xxxxxxxx-xxxx-...`
`DATABRICKS_CLIENT_SECRET`	Service principal secret	`dose...`
`DATABRICKS_HOST`	Workspace hostname. Falls back to the default target in `databricks.yml`	`dbc-46ba3922-f68b.cloud.databricks.com`
`DATABRICKS_HTTP_PATH`	SQL Warehouse HTTP path. Falls back to `env` in `app.yaml`	`/sql/1.0/warehouses/e25d3da675c1b27b`
`APP_MODE`	Enables the yaml fallback when set to `local` (default: `local`)	`local`

Resolution order is .env > databricks.yml / app.yaml > system environment variables (already-set environment variables are never overwritten).

Do not commit .env.

4. Start the Server

Run the frontend and backend in separate terminals.

# Terminal 1: Vite dev server
npm run dev

# Terminal 2: FastAPI
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

Open http://localhost:5173 to verify. API docs are at http://localhost:8000/api/docs (Swagger UI).

The Vite dev server proxies /api to localhost:8000. If you change the backend port, update server.proxy in frontend/vite.config.ts too.

Common Errors

RuntimeError: databricks-sql-connector is not installed

Cause: Python dependencies are not installed. The SQL layer swallows the import error and defers it, so the app itself starts anyway.

Fix:

pip install -r requirements.txt

503 Service Unavailable (Databricks credential configuration is incomplete)

Cause: One of DATABRICKS_HOST / DATABRICKS_HTTP_PATH / DATABRICKS_CLIENT_ID / DATABRICKS_CLIENT_SECRET is missing.

Fix:

# Check the resolved values
python -c "from backend import settings; print(settings.DATABRICKS_HOST, settings.DATABRICKS_HTTP_PATH)"

Add the missing values to .env. Also verify the SQL Warehouse is running.

400 Bad Request (Invalid identifier)

Cause: The catalog / schema / table name does not match ^[A-Za-z0-9_]+$ and is rejected by the SQL-injection allowlist in backend/sql/utils.py.

Fix: Check the identifier. Identifiers containing symbols or spaces are not supported today.

404 Not Found (Frontend not built. Please run 'npm run build' first.)

Cause: backend/static/index.html is missing — you tried to serve the SPA from the backend alone.

Fix:

npm run build

Port 8000 is already in use

Cause: Another process is holding the port.

Fix:

lsof -i :8000
# Kill the process, or start on another port (and update the proxy in vite.config.ts)
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8001