00 Setup

Goal

Have the workshop app running locally with both OpenAI and Langfuse credentials in place. From here you can skim 01-base-app, then start building in 02-tracing.

Prerequisites

Node.js ^20.19.0 || >=22.12.0 — check with node -v and upgrade before installing if you are below it (nvm install 22, or the equivalent for asdf, fnm, or volta).

An older version fails in a way that is easy to misread. Vite's platform-specific binary is an optional dependency, so npm skips it without reporting an error: npm install looks like it succeeded, and the problem only appears later when npm run dev cannot start Vite. If you upgrade Node after installing, re-run npm ci so the skipped binary is fetched.

Starting point

Clone the workshop repository, enter it, then check out the setup checkpoint for this chapter:

git clone https://github.com/langfuse/langfuse-workshop.git
cd langfuse-workshop
git checkout checkpoint/00-setup

This checkpoint intentionally contains the same untraced base app as checkpoint/01-base-app. Use it to confirm that your API keys, dependencies, and local ports work before switching to the build chapters. The Langfuse keys are configured now, but traces start only after you add instrumentation in 02-tracing.

Step 1 — Get the API keys

1. OpenAI — platform.openai.com → API Keys → create one. Copy the sk-... value.
2. Langfuse — sign up at langfuse.com on the EU region, create a project, and copy the public + secret keys from Settings → API Keys.

Step 2 — Install the Langfuse skill and CLI

Later modules drive Langfuse through a coding agent, which needs the langfuse skill and the Langfuse CLI.

Paste this into your coding agent to install both:

"Please install the langfuse skill from https://github.com/langfuse/skills/tree/main/skills/langfuse, and install the Langfuse CLI with npm install -g langfuse-cli."

Prefer to install them yourself:

# Langfuse CLI
npm install -g langfuse-cli

# Langfuse Skill:
npx skills add langfuse/skills --skill "langfuse"

Step 3 — Configure .env

cp .env.example .env

Fill in:

OPENAI_API_KEY=sk-...
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

Leave the rest of the defaults as they are.

The workshop app always loads this repository's .env file for the server and helper scripts. If you have LANGFUSE_*, OPENAI_*, or DATASET_NAME values exported in your shell from another project, they will not override this file. To change the workshop configuration, edit .env.

Keep these values in your local .env only. Do not paste real API keys into shared workshop notes, transcripts, screenshots, or chat messages.

Step 4 — Install and run

npm install
npm run dev

Open http://127.0.0.1:3333.

If you want to verify the server separately, check http://127.0.0.1:8787/api/health or http://127.0.0.1:8787/api/support-context. During npm run dev, 127.0.0.1:8787/ is not the main app URL.

If nothing loads on 127.0.0.1:3333, scroll the npm run dev output back to the [dev:client] lines. concurrently keeps the API server running even when Vite has crashed, so the terminal still looks alive — and opening 127.0.0.1:8787/ in that state answers with ENOENT ... dist/index.html, which only means the production build is absent and says nothing about the real failure. A Cannot find native binding crash in those [dev:client] lines is the Node version; see Prerequisites.

Step 5 — Confirm what you see

You should see the Dad IT Support Agent chat:

• the Specs mascot up top
• a greeting from Specs
• suggestion chips below the greeting
• the iPhone panel on the right ("Dad" + iPhone 15 details)

How to verify you are done

• npm run dev is running and listening on http://127.0.0.1:3333 (client) and http://127.0.0.1:8787 (API server).
• http://127.0.0.1:8787/api/health or http://127.0.0.1:8787/api/support-context returns a real response.
• The browser shows the Specs greeting, not an error.
• Sending one of the suggestion chips returns a real iPhone answer from the model.

End state

Your environment is ready. To build the workshop step-by-step, skim 01-base-app if you want the app tour, then check out checkpoint/02-tracing for the first code changes.