LIF — Linux ISO Finder

LIF is a self-hosted BitTorrent DHT indexer and full-text search engine. It discovers public torrent metadata, stores it in SQLite, and exposes a Web interface for searching and monitoring the index.

Highlights

• Passive and active discovery over the BitTorrent DHT, including BEP 51 sampling.
• Metadata retrieval through BEP 9/BEP 10, peer exchange, and tracker discovery.
• Unicode-aware SQLite FTS5 search across torrent names and file paths.
• Exact totals, stable sorting, snippets, and bounded pagination on large indexes.
• Recent and popularity feeds with persistent observation counters.
• Live indexing, DHT, worker, PEX, and coverage metrics.
• Progressive database recovery with a bounded two-page backlog queue.
• Structured runtime traces and graceful shutdown.
• Single Go binary, embedded Web assets, and no CGO requirement.

Screenshots

Search

Indexing status

Quick start

Requirements:

• Go 1.26.4 or newer.
• Network access for DHT, peers, and trackers.
• UDP port 6881 reachable when public DHT participation is desired.

Build and start LIF:

git clone https://github.com/J4GL/LIF.git
cd LIF
cp config.example.toml config.toml
go build -o lif ./cmd/lif
./lif -config config.toml

Open http://localhost:12345. The SQLite database is created and migrated automatically at the configured database.path.

Useful flags:

-config <path>       configuration file (default: config.toml)
-debug               enable structured debug traces
-version             print build information
-reset-index <path>  irreversibly reset an index; requires -confirm-reset

Configuration

Copy config.example.toml to the ignored local config.toml, then adjust it for your host. The example documents all runtime settings:

[server]
host = "0.0.0.0"
port = 12345

[database]
path = "./lif.db"

[rate_limit]
search_per_minute = 20

Concurrency limits for DHT queries, metadata fetches, peer connections, and tracker announces are validated before startup. Tune them gradually and monitor the Status page.

Architecture

BitTorrent DHT / BEP 51
          │
          ▼
  discovery pipeline ──────► metadata / PEX / trackers
          │                            │
          └──────────────┬─────────────┘
                         ▼
                 SQLite + FTS5
                         │
                         ▼
                  HTTP API + UI

The current generated module and function call graph is maintained locally in the specs directory.

Search performance

The PERF-005 regression fixture contains 10,000 torrents and 500,000 files. A broad search that previously exceeded a 240-second command timeout completes in approximately 1.14 seconds on the reference development machine while preserving an exact total. The automated local budget is 2 seconds.

The query plan, benchmark protocol, and invariants are documented in the local specs directory.

Production service

A hardened systemd unit and installation script are provided for Linux:

git clone https://github.com/J4GL/LIF.git
cd LIF
go build -o lif ./cmd/lif
sudo ./deploy/install.sh
sudo systemctl enable --now lif
journalctl -u lif -f

The installer uses /etc/lif/config.toml, /var/lib/lif/lif.db, and the dedicated lif system account.

To remove the service and its data:

sudo systemctl disable --now lif
sudo rm /etc/systemd/system/lif.service
sudo systemctl daemon-reload
sudo rm /usr/local/bin/lif
sudo rm -r /etc/lif /var/lib/lif
sudo userdel lif

Updating the production service

Pull the latest source, rebuild, and re-run the installer. The installer stops the running service, replaces the binary, and keeps your existing configuration and database:

git pull
go build -o lif ./cmd/lif
sudo ./deploy/install.sh
sudo systemctl start lif

Notes:

• /etc/lif/config.toml and /var/lib/lif/lif.db are preserved; the installer only forces the database path to /var/lib/lif/lif.db.
• No config changes are required between releases: new pipeline settings fall back to documented defaults.
• Verify the update with systemctl status lif and journalctl -u lif -f.

Development and tests

GitHub Actions validates the native executable and a Chromium smoke test on every supported operating system:

System	Native Go	Chromium smoke	Visual references
Ubuntu 24.04	Yes	Yes	—
Windows Server 2025	Yes	Yes	—
macOS 15	Yes	Yes	Yes

On Windows, build and launch the executable with go build -o lif.exe ./cmd/lif and .\lif.exe -config config.toml.

go test ./...
go vet ./...
npm ci
npm run test:e2e:smoke
npm run test:e2e:web

Web end-to-end tests use Playwright. CI uses one Playwright worker and a four-times latency allowance for shared runners; local performance budgets remain unchanged. macOS visual checks allow at most 1% pixel drift for machine-dependent text rasterization. Performance tests also assert SQLite query plans so a fast machine cannot hide an accidental full-table scan.

TODO

• Improve search quality, relevance, and response time.
• Speed up torrent discovery across DHT, BEP 51, peers, and trackers.

Responsible use

LIF observes metadata announced on public BitTorrent infrastructure. Operators are responsible for complying with applicable laws, network policies, and resource constraints. LIF does not host or distribute payload data.

License

LIF is available under the MIT License.