Setup & Running

Datagrunt Studio is open source on GitHub and MIT-licensed. There are two ways to run it: directly on your machine (best for day-to-day development), or as prod-like container images with a single make up.

Prerequisites

Node.js 22+
uv — manages Python 3.10+ for you; no separate Python install needed

Clone the repository first:

git clone https://github.com/pmgraham/datagrunt-studio.git
cd datagrunt-studio

Run Locally

Studio is two processes: a FastAPI backend sidecar (Datagrunt + DuckDB) and a Next.js frontend.

1. Backend (first terminal):

cd backend
uv sync --extra dev
uv run uvicorn app.main:app --reload

2. Frontend (second terminal):

npm ci
npm run dev

3. Open http://localhost:3000. The UI proxies API calls to the backend at BACKEND_URL (default http://127.0.0.1:8000).

The backend is deliberately a single-user, loopback-only companion process — it has no authentication because it is designed to run on and serve only your machine. Don’t expose it to a network.

Run with Containers

For a prod-like run of the built app, use the Makefile. make up works on any machine: it uses Apple Container when its container CLI is installed (macOS), and Docker Compose otherwise.

make up      # build images as needed (slow the first time; cached after),
             # stage credentials, start backend & frontend; UI at http://localhost:3000
make logs    # print logs
make down    # stop and remove
make status  # list containers
make build   # build the images without starting anything

macOS / Apple Container one-time setup: run container system start (add --enable-kernel-install if it reports no kernel is configured). After the first build, startup takes only a few seconds — the images boot as lightweight VMs. Backend data persists in .container-data/ between runs.

Docker hosts: prefer make up over raw docker compose up so Google Cloud credentials get staged — a raw docker compose up mounts an empty /secrets, and GCS import stays disabled until you run make up (or make stage-adc). The same docker-compose.yml doubles as the deploy config for a generic Docker host; the images are standard OCI: backend/Dockerfile (FastAPI, port 8000) and Dockerfile (Next.js standalone, port 3000, expects BACKEND_URL).

Configuration

All configuration is optional — Studio works out of the box for local files. Copy the template and fill in only what you use:

cp .env.example .env

Setting	Needed for	Notes
`GEMINI_API_KEY`	AI PDF rationalization via Gemini	See AI PDF Extraction. Not needed for Vertex AI or Ollama.
Application Default Credentials	GCS import/export, Vertex AI	No `.env` entry needed — run `gcloud auth application-default login` once. Under `make up`, credentials are automatically staged into the gitignored `.container-secrets/` (refreshed on every `make up`).
`GOOGLE_ADC_FILE`	GCS under containers	Only if your ADC file lives somewhere non-standard.
`OLLAMA_HOST`	Local LLM at a non-default address	Only if your Ollama daemon isn’t at the default address.

Local Ollama under containers

The AI PDF Extractor’s Use local LLM (Ollama) option talks to your host’s Ollama daemon. make up points the backend container at the host automatically — but from inside a container, localhost is the container itself, so the host daemon must listen on a non-loopback interface:

OLLAMA_HOST=0.0.0.0 ollama serve

Native (non-container) runs need no such step.

Importing Data