ContextQMD
Back to Openviking

Vikingbot Langfuse Local Setup

bot/docs/vikingbot-langfuse-local-setup.md

0.3.166.0 KB
Original Source

Vikingbot Langfuse Local Setup

Author: OpenViking Team Status: Draft Date: 2026-04-29

1. Purpose

This document describes how to bring up a local Langfuse service for vikingbot, connect it through openviking-server --with-bot, and verify that traces are arriving.

This guide is for local development and validation. It uses the repository's bundled Docker Compose deployment and the default local credentials baked into that deployment.

2. What You Get

After setup completes, you should have:

  1. A local Langfuse UI at http://localhost:3000
  2. A working bot.langfuse configuration in ~/.openviking/ov.conf
  3. vikingbot traces tied to your real bot traffic
  4. response_id visible in Langfuse metadata for Phase 1 validation

3. Prerequisites

Before starting, make sure:

  1. Docker is installed and the daemon is running
  2. docker compose is available, or docker-compose is installed
  3. Your local OpenViking environment can start with openviking-server --with-bot
  4. Your bot already has a usable model configuration in ov.conf

If Docker image pulls fail in your environment, fix Docker daemon network access or proxy settings before continuing.

4. Deploy Local Langfuse

Run the bundled deployment script:

bash
cd bot/deploy/docker
./deploy_langfuse.sh

The script starts the Langfuse stack from bot/deploy/docker/langfuse/docker-compose.yml.

Expected local endpoints and credentials:

  • Web UI: http://localhost:3000
  • Admin email: [email protected]
  • Admin password: vikingbot-admin-password-2026
  • Public key: pk-lf-vikingbot-public-key-2026
  • Secret key: sk-lf-vikingbot-secret-key-2026

If the script succeeds, verify the containers are running:

bash
docker compose -f bot/deploy/docker/langfuse/docker-compose.yml ps

If your machine only has docker-compose, use:

bash
docker-compose -f bot/deploy/docker/langfuse/docker-compose.yml ps

5. Install Langfuse Python Support

vikingbot only sends Langfuse traces when the optional Langfuse dependency is installed.

From the repository root, install it with:

bash
uv pip install -e ".[bot,bot-langfuse]"

If your environment already has the main bot dependencies installed, the smaller install also works:

bash
uv pip install -e ".[bot-langfuse]"

6. Configure ov.conf

Add the following to ~/.openviking/ov.conf:

json
{
  "bot": {
    "langfuse": {
      "enabled": true,
      "secret_key": "sk-lf-vikingbot-secret-key-2026",
      "public_key": "pk-lf-vikingbot-public-key-2026",
      "base_url": "http://localhost:3000"
    }
  }
}

Key meaning:

  1. secret_key: server-side ingestion credential used by vikingbot
  2. public_key: paired project key stored alongside the secret key
  3. base_url: local Langfuse service address

For local repository deployment, keep base_url as http://localhost:3000.

7. Restart OpenViking With Bot

After updating ov.conf, restart the service path you actually use for validation:

bash
openviking-server --with-bot

Expected startup behavior:

  1. OpenViking HTTP server listens on 127.0.0.1:1933
  2. Bot API proxy is exposed at /bot/v1
  3. Internal vikingbot gateway starts automatically

If Langfuse is enabled correctly, startup logs should indicate Langfuse is enabled with the configured base URL.

8. Verify End-to-End

8.1 Check Bot Health

bash
curl -sS http://127.0.0.1:1933/bot/v1/health

Expected result: HTTP 200.

8.2 Send a Test Chat Request

bash
curl -sS -X POST "http://127.0.0.1:1933/bot/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "langfuse-local-verify-session",
    "user_id": "langfuse-local-verify-user",
    "message": "Please reply with one short sentence for Langfuse verification."
  }'

Expected result:

  1. The top-level response contains response_id
  2. The final response event contains data.response_id
  3. Both values match

8.3 Check Langfuse UI

Open http://localhost:3000 and sign in with:

  1. Email: [email protected]
  2. Password: vikingbot-admin-password-2026

Find the trace generated by the test request and inspect the generation metadata.

For Phase 1, verify:

  1. The trace exists for your request
  2. Generation metadata includes response_id
  3. Tool spans, if any, also include response_id
  4. session_id and user_id are attached to the trace

8.4 Cross-Check Session Storage

If you also want to verify persistence, inspect the session JSONL under the bot data directory. By default this is:

text
~/.openviking/data/bot/sessions/

The assistant message for the request should include the same response_id you saw in the HTTP response and Langfuse.

For the full Phase 1 verification checklist, see:

  • bot/docs/vikingbot-phase1-validation-with-openviking-server.md

9. Troubleshooting

9.1 Langfuse UI Does Not Open

Check whether the containers are up:

bash
docker compose -f bot/deploy/docker/langfuse/docker-compose.yml ps

Then inspect logs:

bash
docker compose -f bot/deploy/docker/langfuse/docker-compose.yml logs -f

If you use docker-compose, replace the command accordingly.

9.2 No Traces Show Up in Langfuse

Check the following first:

  1. uv pip install -e ".[bot-langfuse]" or uv pip install -e ".[bot,bot-langfuse]" has been run in the active environment
  2. bot.langfuse.enabled is true in ~/.openviking/ov.conf
  3. secret_key, public_key, and base_url match the local deployment values
  4. openviking-server --with-bot was restarted after the config change

9.3 Docker Pull Fails

Typical causes are:

  1. The Docker daemon cannot reach upstream registries
  2. Your machine needs an outbound proxy for Docker
  3. A company network policy blocks anonymous registry access

Resolve Docker connectivity first, then rerun the deployment script.

  • Feedback observability design: bot/docs/vikingbot-feedback-observability-design.md
  • Phase 1 validation: bot/docs/vikingbot-phase1-validation-with-openviking-server.md