kindexr/README.md

# kindexr

A Nostr-native Torznab indexer. Subscribes to NIP-35 torrent events on the Nostr relay network and serves them through the Torznab API that Sonarr, Radarr, Lidarr, Readarr, and Prowlarr already speak.

**Same slot as Jackett or Prowlarr** — middleware between Nostr and the *arr automation stack. Not a frontend, not a relay, not a downloader.

## What it does

- Connects to Nostr relays and indexes kind 2003 (NIP-35) torrent events into a local SQLite database
- Serves indexed content as a Torznab API endpoint for *arr apps
- Enriches metadata via TMDB (movies and TV shows get proper IDs for *arr matching)
- Filters publishers using Web of Trust (WoT) — trust scores derived from your Nostr follow graph, with manual vouch/block/mute controls
- Publishes torrents back to Nostr from a connected **qBittorrent** or **Deluge** instance
- Fetches publisher profiles (kind 0) so you see names and avatars instead of raw pubkeys
- Web UI at `/ui` — dashboard, indexed content browser, publisher management, publish queue, settings

## Quick start

### Build

```sh
just build
# produces target/release/kindexr and target/release/kindexr-cli
```

### Configure

```sh
sudo mkdir -p /etc/kindexr /var/lib/kindexr
sudo cp deploy/kindexr.example.yaml /etc/kindexr/config.yaml
sudo $EDITOR /etc/kindexr/config.yaml
```

Create the service user:

```sh
sudo useradd --system --no-create-home --shell /usr/sbin/nologin kindexr
sudo chown kindexr:kindexr /var/lib/kindexr
```

### Install and start

```sh
sudo just install
sudo systemctl daemon-reload
sudo systemctl enable --now kindexr
sudo journalctl -u kindexr -f
```

### Verify

```sh
curl http://localhost:9117/health
# {"status":"ok","version":"...","db_ok":true,"relays_configured":10,"relays_connected":10,"uptime_seconds":0}
```

### Add to Sonarr/Radarr

Add kindexr as a Torznab indexer:

- URL: `http://127.0.0.1:9117` (or your public URL behind nginx)
- API key: generate at `/ui/settings` or with `kindexr-cli apikey create --label sonarr`

## Publishing to Nostr

kindexr can publish torrents back to the Nostr network as kind 2003 events. Two torrent clients are supported:

### Deluge

Enable the Deluge poller in config or via the Settings UI. kindexr connects to the Deluge Web UI JSON-RPC API, polls for completed torrents, and publishes them. Set a label filter (e.g. `publish-nostr`) to only publish specific torrents, or leave labels empty to publish everything completed.

```yaml
publisher:
  enabled: true
  nsec: "nsec1..."
  deluge:
    enabled: true
    url: "http://127.0.0.1:8112"
    password: "your-deluge-web-password"
    poll_interval_secs: 60
    labels: ["publish-nostr"]   # empty = all completed
```

### qBittorrent

```yaml
publisher:
  enabled: true
  nsec: "nsec1..."
  qbittorrent:
    url: "http://127.0.0.1:8080"
    username: "admin"
    password: "adminadmin"
    poll_interval_secs: 60
    categories: ["publish-nostr"]
```

### Manual publish

Drop .torrent files into the publish queue via CLI:

```sh
kindexr-cli publish --from /path/to/torrents/
```

## CLI

```sh
# API key management
kindexr-cli apikey create --label sonarr
kindexr-cli apikey list

# Publisher identity
kindexr-cli identity init                       # generate a fresh keypair
kindexr-cli identity init --nsec <nsec1...>     # import existing key
kindexr-cli identity info

# Enqueue torrent files for publishing
kindexr-cli publish --from /path/to/torrents/
```

## Configuration

See `deploy/kindexr.example.yaml` for a fully commented configuration reference.

Config is loaded in order: **defaults → YAML file → environment variables** (`KINDEXR_` prefix) → **Settings UI** (stored in SQLite, applied at startup).

Example env override:

```sh
KINDEXR_LOGGING_LEVEL=debug kindexr --config /etc/kindexr/config.yaml
```

## Web UI

Available at `http://localhost:9117/ui`:

| Page | Path | What it shows |
|---|---|---|
| Dashboard | `/ui` | Relay status, ingest stats, publish queue |
| Content | `/ui/content` | Browsable index of indexed torrents |
| Publishers | `/ui/publishers` | Publisher list with WoT trust levels |
| Queue | `/ui/queue` | Publish queue and history |
| Settings | `/ui/settings` | All config options, API key management |

## Development

```sh
just test    # cargo test
just check   # cargo clippy + fmt check
just build   # cargo build --release
```

For a local dev run without installing:

```sh
cp deploy/kindexr.example.yaml kindexr.dev.yaml
# edit kindexr.dev.yaml
./target/release/kindexr --config kindexr.dev.yaml
# UI at http://localhost:9117/ui
```

## Architecture

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design.

## License

MIT