tom79/Holos-Discover
1
7
Fork 0
Code Issues 4 Pull requests Releases Activity
Privacy-first Fediverse search engine using native ActivityPub federation; indexes only consenting users with instant deletion support https://discover.holos.social
86 commits 2 branches 11 tags 1,023 KiB
  • TypeScript 50.9%
  • JavaScript 24.2%
  • CSS 14.2%
  • Handlebars 10.7%
Find a file
Thomas 5169ae8d64 - Release 1.2.9
2026-03-07 10:44:56 +01:00
doc - Fix #7 - Add bot filter and authorIsBot field to API responses 2026-03-07 10:44:18 +01:00
public - Fix #7 - Add bot filter and authorIsBot field to API responses 2026-03-07 10:44:18 +01:00
src - Fix #7 - Add bot filter and authorIsBot field to API responses 2026-03-07 10:44:18 +01:00
tests/unit initial commit 2026-02-23 17:14:14 +01:00
.env.example - Add multi-tag timeline endpoint 2026-03-01 12:45:17 +01:00
.gitignore initial commit 2026-02-23 17:14:14 +01:00
LICENSE initial commit 2026-02-23 17:14:14 +01:00
package-lock.json - Add RSS/Atom feeds for trending and timeline 2026-03-01 17:03:22 +01:00
package.json - Release 1.2.9 2026-03-07 10:44:56 +01:00
README.md - Add CLI documentation with crontab examples 2026-03-05 10:04:15 +01:00
tsconfig.json initial commit 2026-02-23 17:14:14 +01:00
vitest.config.ts initial commit 2026-02-23 17:14:14 +01:00

README.md

Holos Logo

Holos Discover

A Fediverse search engine

Translation status

A search engine that respects user privacy and consent. It federates via ActivityPub to index public content from users who have explicitly enabled indexing.

How It Works

Consent-Based Indexing

We only index content from users who have consented:

  • indexable=true - User has enabled search engine indexing
  • Not locked - Account does not require follow approval
  • No #nobot - Bio does not contain #nobot or #noindex

The Snowball Effect

  1. Admin adds initial users via npm run add-user
  2. We send Follow requests to consenting users
  3. When accepted, their posts arrive in our inbox
  4. We discover new users from mentions, boosts, and replies
  5. We automatically follow new consenting users
  6. The network grows organically

User Commands

Users can control their indexing by mentioning the bot:

Command Action
@HolosDiscover follow Request to be indexed (if consent settings allow)
@HolosDiscover unfollow Stop indexing and remove content

Privacy

  • Following list hidden - We don't expose who we index
  • Consent required - No indexing without explicit opt-in
  • Blocking works - Block us to have your content removed
  • #nobot respected - Bio markers prevent indexing

Architecture

Stack

  • Runtime: Node.js 22+
  • Database: PostgreSQL (full-text search)
  • Queue: Redis + BullMQ
  • Protocol: ActivityPub

Components

Component Description
ActivityPub Endpoints /inbox, /actor, /outbox, /followers, /following
Inbox Workers Process Create, Delete, Update, Announce, Block activities
Discovery Worker Follow new consenting users found in content
Signature Service HTTP Signatures for authenticated federation

ActivityPub Activities

Received Action
Create Index public post if author consents
Delete Remove post from index
Update Update post or check consent changes
Announce Index boosted post if author consents
Block Remove all content from blocking user
Sent When
Follow Adding a user to index
Undo Follow Removing a user from index
Block Blocking an instance or user
Accept Someone follows us (relay mode)

Documentation

Document Description
doc/install.md Installation and configuration guide
doc/api.md REST API reference for client integration
doc/cli.md CLI commands reference

Quick Start

See doc/install.md for full installation instructions.

git clone https://codeberg.org/tom79/Holos-Discover.git
cd Holos-Discover
npm install
cp .env.example .env
# Edit .env with your settings
npm run dev

License

AGPL-3.0