# Okapi install guide — Phoenix

Okapi speaks the Sentry ingest wire format: this is the standard `sentry` SDK, pointed at your own Okapi instance instead of Sentry's.

The DSN in this generic guide is a placeholder. Get the real DSN from Project → Settings → DSN Keys. An agent with an admin Okapi MCP credential can also call `get_dsn`. Do not invent a DSN.

Do not run the Sentry wizard or any setup that signs in to Sentry's hosted service; nothing in this setup should contact it.

## 1. Install

### `mix.exs`

```elixir
# Inside deps, then run mix deps.get
{:sentry, "~> 14.0"},
{:finch, "~> 0.21"}
# Elixir < 1.18 also needs: {:jason, "~> 1.4"}
```

## 2. Initialize

### `config/prod.exs`

```elixir
config :sentry,
  dsn: "http://YOUR_PUBLIC_KEY@YOUR_OKAPI_HOST/YOUR_PROJECT_ID",
  environment_name: "production",
  # We expect this logger to catch Bandit crashes: PlugCapture is Cowboy-only.
  # Phoenix defaults to Bandit; this is an inference from the SDK logger setup.
  logs: []
```

### `lib/my_app_web/endpoint.ex`

```elixir
defmodule MyAppWeb.Endpoint do
  use Sentry.PlugCapture          # Cowboy only; above use Phoenix.Endpoint
  use Phoenix.Endpoint, otp_app: :my_app

  # ...
  plug Plug.Parsers,
    parsers: [:urlencoded, :multipart, :json],
    pass: ["*/*"],
    json_decoder: Phoenix.json_library()

  plug Sentry.PlugContext         # below Plug.Parsers
end
```

Run mix deps.get after editing deps; replace MyAppWeb and :my_app with your app's names. PlugCapture is Cowboy-only and Phoenix defaults to Bandit; we expect logs: [] to catch Bandit crashes based on the SDK logger setup, rather than a documented Bandit guarantee. With your production environment variables set, use MIX_ENV=prod mix run to load config/prod.exs. If config/runtime.exs requires DATABASE_URL or SECRET_KEY_BASE, set them before the command. Use result: :sync to wait for delivery.

For a deployed release, run `bin/<app> rpc 'Sentry.capture_message("Okapi test event", result: :sync)'`. Replace `<app>` with the release name.

## 3. Send a test event

```bash
MIX_ENV=prod mix run -e 'Sentry.capture_message("Okapi test event", result: :sync)'
```

## 4. Verify

Open the instance's dashboard → Issues. The test event should appear within a few seconds as a new issue. If the instance's MCP server exposes a `verify_installation` tool, call that instead of checking by hand — it reports the SDK name/version and whether only a synthetic test event has arrived yet.

## More

- Structured logs (same DSN, no separate shipper) and source map uploads: https://useokapi.app/docs/sdk-setup
- Connect over MCP once the SDK is wired up: https://useokapi.app/docs/mcp-agents