---
title: "00 Setup"
description: "Learner guide: 00 Setup"
---
# 00 Setup

Workshop material is maintained in the public [`langfuse/langfuse-workshop`](https://github.com/langfuse/langfuse-workshop) repository. Use the repository for the runnable app, checkpoint branches, and local setup.

[View this Markdown file](https://github.com/langfuse/langfuse-workshop/blob/main/docs/instructor/00-setup.md)

Learner guide: [00 Setup](/workshop/learner/00-setup)

## Instructor notes

- Recommend **Langfuse Cloud**, not self-hosted. Supporting self-hosted setups would mean maintaining the workshop against too many Langfuse versions. This workshop is also not about learning how to self-host Langfuse; it is about current features in their most up-to-date form.
- Use `checkpoint/00-setup` as the stable base-app checkout. It should be equivalent to `checkpoint/01-base-app`, not the complete reference app.
- `main` contains the complete reference implementation, but learners should use the checkpoint so setup and base-app orientation share the same starting state.
- Make learners confirm both local services: Vite on `127.0.0.1:3333`, and the Express API on `127.0.0.1:8787/api/health` or `127.0.0.1:8787/api/support-context`.
- Emphasize the EU Langfuse host value: `LANGFUSE_BASE_URL=https://cloud.langfuse.com`.
- The Node server and helper scripts load the repository `.env` with override enabled, so stale exported `LANGFUSE_*`, `OPENAI_*`, or `DATASET_NAME` values from another local project should not win. Have learners edit `.env` when they need to switch keys or projects.
- Do not frontload **Project Settings → LLM Connections** here. Learners configure the default evaluator model in `04-monitoring`, when LLM-as-a-judge evaluators first become relevant.
- Keep key handling explicit: real API keys go only into `.env` or Langfuse secret fields, never into shared transcripts, notes, or chat.
- After one successful chat turn, have learners switch to `checkpoint/02-tracing` for the first build step.

## Watch for

- Missing `.env` values. The app may render while model calls fail.
- Node older than `^20.19.0 || >=22.12.0`. Worth a `node -v` check in the room before anyone runs `npm install`, because npm skips Vite's optional native binary silently and the failure only surfaces later inside `npm run dev`. Learners who upgrade afterwards need `npm ci`, not just a restart.
- People checking `127.0.0.1:8787/` in dev. The API server runs on that port, but the browser app is served by Vite on `127.0.0.1:3333`, so use an API route for the server check. It also hides a crashed Vite: `concurrently` keeps the API server up, and `8787/` answers with `ENOENT ... dist/index.html`.
- Learners editing shell exports instead of `.env`. The workshop intentionally treats `.env` as the Node-side source of truth.
- People expecting evaluator setup during initial setup. The app can run and trace correctly before the Langfuse-side LLM connection exists.
- People wanting to use a company or local self-hosted Langfuse instance. Push them to Cloud so the UI and features match the lessons.
- People expecting traces on `checkpoint/00-setup` or `checkpoint/01-base-app`. Both are intentionally untraced; tracing starts only after the `02-tracing` edits.
- People staying on `main` for tracing. `main` is already the finished reference implementation.

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/workshop/instructor/00-setup.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.