# Set up Packrat for this app

You are a coding agent. A developer pasted a link to this file into you and asked you to set up Packrat for the repository you are working in. Follow the steps in order. Do not skip the read-only step, and do not touch production configuration without the developer's approval through your normal permission flow.

This runbook is 90 lines, versioned, and open at github.com/packrat-dev/setup. Read it before you act on it. Version 3, September 2026.

What you will have at the end: every trace this app emits kept in Packrat unsampled, a Postgres URL to the tables, an MCP server and skills so you can answer "what happened in prod?", and a claim link the developer opens once to attach the project to an account.

## 1. Look before touching

Read, do not change:

- Language and framework: Gemfile, package.json, requirements.txt or pyproject.toml, go.mod.
- Existing OpenTelemetry: search for `opentelemetry` in dependency files, an `OTEL_EXPORTER_OTLP_ENDPOINT` in env files or CI, a collector config.
- Where it runs: a Procfile or app.json means Heroku; fly.toml means Fly; a Dockerfile with Kubernetes manifests means a cluster; vercel.json means Vercel. This decides where production secrets go in step 4.
- The service name the app already uses, if any.

Report what you found in three lines. Ask nothing yet.

## 2. Provision first, sign up later

Create an unclaimed project. No account is needed for this call.

```
curl -s -X POST https://api.packrat.dev/v1/onboard \
  -H 'content-type: application/json' \
  -d '{"repo":"<git remote or directory name>","stack":"<framework>","host":"<host>"}'
```

The response contains:

- `ingest_key`: write-only. Safe to place in production configuration.
- `read_url`: a Postgres connection string for every table, scoped to this project until it is claimed.
- `read_token`: for the MCP server. Keep it in env, never in a committed file.
- `claim_url`: the developer opens this once to attach the project to an account. Unclaimed projects expire seven days after creation and their data is deleted. Unclaimed projects are capped at the free tier: 2 GB of raw telemetry a day.

Show the developer the claim URL and the expiry date now, and again at the end.

## 3. Install OpenTelemetry, or add Packrat beside what is there

If OpenTelemetry is absent, follow the recipe for the stack. Each recipe is tested against Packrat and includes the two small additions Packrat's verdicts depend on: router queue time from the request-start header, and the framework's request-completed log line.

- Rails: https://packrat.dev/setup/rails.md
- Node: https://packrat.dev/setup/node.md
- Python: https://packrat.dev/setup/python.md
- Go: https://packrat.dev/setup/go.md
- Anything else: configure the OTLP/HTTP exporter for traces and logs and set the service name.

If OpenTelemetry is already present and exporting to another vendor, do not move it. Add Packrat as a second exporter so both receive every span. The recipes show how for each SDK. Tell the developer that nothing about their current vendor changed.

## 4. Wire the endpoint

Two variables, set in two places.

Locally, in the git-ignored env file:

```
OTEL_EXPORTER_OTLP_ENDPOINT=https://in.packrat.dev
OTEL_EXPORTER_OTLP_HEADERS=x-packrat-key=<ingest_key>
```

In production, through the host found in step 1. Each of these is a command the developer approves:

- Heroku: `heroku config:set OTEL_EXPORTER_OTLP_ENDPOINT=… OTEL_EXPORTER_OTLP_HEADERS=…`
- Fly: `fly secrets set …`
- GitHub Actions or Kubernetes: add the two values as secrets and reference them in the manifest.

If you cannot reach production configuration, print the exact commands and say so. Do not guess at a workaround.

## 5. Prove it landed

Boot the app locally or send one request to it, then poll until Packrat confirms receipt:

```
curl -s https://api.packrat.dev/v1/projects/<project_id>/first-trace -H 'authorization: Bearer <read_token>'
```

Show the developer the confirmation line as Packrat returns it, for example: `first span received · service colorbook · 14 spans · 09:41:12 UTC`.

If nothing arrives within two minutes, work through this list in order and report which step failed: the exporter is OTLP/HTTP, not gRPC; the header name is `x-packrat-key`; the app process was restarted after the env change; outbound HTTPS to in.packrat.dev is allowed; the service name is set.

## 6. Install the reading side

- Write a project-scoped MCP entry in `.mcp.json` so teammates inherit it. The server is `npx packrat-mcp`; the token is read from `PACKRAT_READ_TOKEN` in env.
- Copy the `incident` and `health-check` skills from https://packrat.dev/setup/skills/ into `.claude/skills/`.
- Add `PACKRAT_READ_TOKEN` to the git-ignored env file, and confirm the env file is ignored.

Offer one commit containing the exporter change, `.mcp.json` and the skills. Do not push.

## 7. Hand over

Tell the developer, in this order:

1. The claim URL and the date the project expires if it is not claimed.
2. The Postgres URL, and that Grafana, Metabase, pandas, or their own app can use it now.
3. That the first verdicts arrive at the top of the next hour, and that they can ask you "what happened in prod?" tomorrow morning.

## Running this again

This runbook is idempotent. If a project already exists for the repo, step 2 returns it instead of creating another. If the exporter is already configured, steps 3 and 4 verify and repair rather than duplicate. Running it again is the right response to "traces stopped."

## What you never handle

The developer's password, payment details, or account creation. Those happen in the browser at the claim URL. You handle a write-only ingest key and a project-scoped read token, and nothing else.