A search engine that makes videos across the whole PeerTube network actually findable
Peerseek is a federated video search engine for PeerTube. It continuously crawls public PeerTube instances, indexes their videos in PostgreSQL, and serves a fast JSON API and web UI at peerseek.video. At the time of writing it indexes roughly 940,000 videos from about 1,600 instances. It is written in Go.
Why I built this#
I run MakerTube, a PeerTube instance for makers, DIY, and engineering content. I host my own synth-building videos there and wanted a home on the fediverse that isn’t a recommendation algorithm optimized against me. PeerTube is genuinely great for that: you own your instance, there are no ads, no tracking, and the network keeps gaining momentum.
But running an instance for a while taught me where the friction is: discovery. To be fair, PeerTube already has search. The official SepiaSearch lets you type a query and find videos across many instances, and it works well for that — if you know roughly what you are looking for, you can find it.
What is missing is everything around that search box. There is no good way to just browse the network: no front page of fresh, interesting videos, no feed that adapts to what you like, no sense of a welcoming place to wander into when you do not have a specific query in mind. SepiaSearch answers “find me this”; it does not answer “show me something good right now.” So fresh and personalized content stays hard to reach, and a video on a small instance still tends to sit unseen.
That has real consequences. My experience with MakerTube — and a story I hear from a lot of other instance admins — is steady but slow growth and generally low engagement, even while PeerTube itself is doing well. Good videos get uploaded and then sit there because the audience that would love them never finds them.
So Peerseek is my attempt at the missing piece: not just a query box, but a fast, privacy-respecting place to browse the federated network — a home feed of fresh, ranked, personalized videos that is built to surface smaller creators instead of burying them.
How search and personalization work#
The goal is that the front page already feels relevant before you type anything, and that searching returns results ranked by quality rather than just keyword matches.
Ranking#
Results are scored from several independent signals that are combined into a single relevance score:
- Text relevance – how well the title/description/tags match your query (PostgreSQL full-text search).
- Engagement – likes and comments relative to views, with a trust rule that discards videos showing implausibly inflated view counts.
- Freshness – newer uploads get a decaying boost so the feed doesn’t feel stale.
- Click-through rate – aggregate, anonymous click behavior per channel nudges consistently interesting creators up.
- Personalization – an optional, privacy-friendly nudge based on what you tend to watch (see below).
There’s also a per-account diversity cap so a single prolific channel can’t dominate a page, and a small “evergreen” slot that occasionally resurfaces older, popular videos.
Privacy-friendly personalization#
Personalization on Peerseek has no user accounts and stores no personal data. There is no login, no email, no tracking pixel.
Instead, your browser generates a random profile_token and keeps it in localStorage. A lightweight, anonymous profile (which categories, languages, and channels you interact with) is associated with that token and used only to gently re-weight the home feed toward things you’re likely to enjoy. You can clear it any time by clearing site data, and the personalization term can be turned off entirely. The default weight is deliberately small so it tilts the feed rather than trapping you in a bubble.
Filters#
On top of ranking you can narrow results with a set of filters:
| Filter | What it does |
|---|---|
| Query | Free-text search across titles, descriptions, and tags |
| Sort | relevance, date (newest), views, or trending |
| Category | PeerTube category (Science & Technology, Music, etc.) |
| Language | Filter by the video’s language |
| Instance | Restrict to a single PeerTube host |
| Followed channels | A dedicated rail for channels you follow |
| NSFW | Off by default; opt in to include sensitive content |
trending and views are sorted in the database, while relevance is ranked in the application so the quality signals above can be applied.
Technical overview#
Peerseek is a set of small Go services backed by PostgreSQL and Valkey, deployed on Kubernetes. There is deliberately no OpenSearch or Elasticsearch — Postgres full-text search turned out to be more than fast enough for a corpus this size and dramatically simpler to operate.
The crawler#
Crawling is split into a scheduler and a pool of workers that communicate through a Valkey (Redis-compatible) queue:
- The scheduler periodically fetches the public instance list from joinpeertube.org, filters out blacklisted hosts, and enqueues crawl jobs. It uses a hybrid strategy: it always re-checks the newest page of each instance (so fresh uploads show up quickly) while also resuming deeper pagination for instances whose back-catalog isn’t fully indexed yet.
- Workers pull jobs from the queue, enforce per-host rate limiting to stay polite to each instance, fetch video pages from the PeerTube
/api/v1/videosAPI, filter blacklisted accounts, and batch-upsert the results into Postgres. Failures are retried with exponential backoff and eventually dead-lettered. - A separate tag-backfill pass fills in detailed tags for videos that the list endpoint returns without them, tracking progress so truly tagless videos aren’t retried forever.
- A retention job drops videos from instances that have gone dark and haven’t been seen in a long time, so the index reflects what’s actually online.
The database#
Everything lives in a single primary videos table (~30 columns of denormalized channel, account, and category data) plus supporting tables for instances and blacklists. Full-text search uses a tsvector column with a GIN index, kept up to date automatically by a Postgres trigger on insert/update. Search queries run through plainto_tsquery against that index; the relevance ranking then happens in Go.
Basic API reference#
The same API that powers the web UI is public. The main endpoint is:
GET https://peerseek.video/v1/search?q=blender
Supported query parameters:
| Parameter | Description |
|---|---|
q | Search query (free text) |
sort | relevance (default), date, views, trending |
category | Filter by category label |
language | Filter by language code (e.g. en) |
instance | Filter by instance host |
include_nsfw | true to include sensitive content |
page | Page number (1-based) |
size | Results per page |
A response is JSON with a total, page, size, and a videos array; each video includes its title, description, channel and account, instance host, category, language, counts (views, likes, comments), publish date, thumbnail, and a direct watch URL on the originating instance. There’s also /v1/filters for the available categories, languages, and instances. Full details are on the FAQ page.
Getting your instance indexed#
Peerseek discovers instances from the public PeerTube instance index that the joinpeertube.org instance list is built from. If you run a PeerTube instance and want your videos to show up in Peerseek, make sure your instance is listed there and publicly reachable — that is how the crawler finds it in the first place.
The crawler also respects robots.txt. It identifies itself with a descriptive user agent and stays polite with per-host rate limiting, so if you would rather not be crawled you can disallow it via your robots.txt.
Resources#
- Peerseek – The live search engine
- MakerTube – My PeerTube instance for makers
- PeerTube – The federated video platform
- SepiaSearch – The official PeerTube search
