Selfoss

Selfoss is a lightweight, PHP‑based web application that aggregates RSS/Atom feeds and other content streams into a single, searchable interface. From a developer’s perspective it functions as both an end‑to‑end feed reader and a programmable data pipeline: feeds are fetched, parsed, stored in a relational database, and exposed via a RESTful JSON API that can be consumed by custom dashboards, mobile clients or other automation tools. The application is intentionally minimalistic—about 25 MB of code—and relies on standard web server components (Apache/Nginx with PHP 8.x) and a choice of MySQL, PostgreSQL or SQLite for persistence. This makes it trivial to embed in existing PHP stacks or to run as a standalone service behind a reverse proxy.

Architecture

Selfoss follows a classic Model‑View‑Controller pattern, with the PHP codebase split into:

• Core – feed ingestion (cliupdate.php), parsing, deduplication and database schema migrations.
• API – a set of REST endpoints (/api/...) that expose feeds, entries, categories and user preferences. The API uses JSON and supports pagination, filtering by tag or source, and bulk updates.
• Web UI – a responsive Blade‑style template engine (built on pure PHP) that renders the feed list, article previews and administrative panels. The UI is mobile‑first and can be customized via CSS or the built‑in theme system.
• Plugin System – a hook‑based architecture where third‑party connectors can register new data sources (e.g., Twitter, Mastodon) or modify the feed import pipeline. Plugins are simple PHP classes that implement a defined interface, making extension straightforward for developers familiar with OOP.

The database layer is abstracted through PDO, allowing the same code to run on MySQL, PostgreSQL or SQLite. Auto‑migration scripts create tables and triggers on first run; subsequent upgrades are handled via an internal migration manager that applies incremental changes without manual intervention.

Core Capabilities

• Feed Ingestion – Supports RSS 2.0, Atom 1.0, JSON‑feed and custom XML formats via the plugin API.
• RESTful API – Endpoints for listing feeds, fetching article metadata, marking read/unread, and bulk operations. The API is stateless and uses token‑based authentication (API key stored in config.ini).
• Search & Tagging – Full‑text search powered by the underlying database (MySQL FULLTEXT or PostgreSQL tsvector). Articles can be tagged, favorited and sorted.
• Webhooks & Callbacks – Optional webhook support to notify external services when new items arrive or on user actions.
• OPML Import/Export – Allows migration from other readers; the import routine parses OPML files and creates corresponding feeds.

Deployment & Infrastructure

Selfoss is designed for self‑hosting scenarios:

• Server Requirements – PHP 8.x, cURL, JSON, XML extensions; any web server that can execute PHP. No external services are required.
• Containerization – Official Docker images are available on Docker Hub, simplifying deployment in Kubernetes or Docker Compose environments. The image exposes the web UI and a cron job container that triggers /update via curl.
• Scalability – While a single instance is sufficient for personal use, the stateless API and database‑backed storage allow horizontal scaling behind a load balancer. The cron job can be distributed across nodes using shared database or message queues if needed.
• Backup & Restore – The data/ directory holds cache, favicons and thumbnails; the database is fully portable. Developers can script backups with simple mysqldump/pg_dump or SQLite file copies.

Integration & Extensibility

The plugin system is the primary extension point. Developers can write connectors that fetch data from any API, transform it into feed items and register them with Selfoss. The hooks cover:

• Pre‑processing – modify raw XML/JSON before parsing.
• Post‑processing – enrich entries (e.g., add thumbnails, sentiment scores).
• Authentication – plug in OAuth or API key handling for protected sources.

The REST API can be consumed by custom clients (React dashboards, CLI tools) or integrated into existing enterprise workflows. Webhooks provide real‑time integration with CI/CD pipelines, monitoring dashboards or home automation systems.

Developer Experience

• Configuration – A single config.ini file holds all runtime options, from database DSN to API key and cron interval. The file is well‑documented in the README and linked examples.
• Documentation – The project includes a comprehensive wiki, API reference, and contribution guide. Community support is active on GitHub Issues, the dedicated forum, and Gitter chat.
• Testing – The codebase ships with PHPUnit tests covering core ingestion logic and API endpoints, making it safe to fork or extend.

Use Cases

• Personal Knowledge Base – Aggregate blogs, news sites and social feeds into a searchable archive.
• Enterprise Content Hub – Centralize internal newsletters, product updates and third‑party feeds for employee consumption.
• Developer Tooling – Build custom dashboards that expose feed data via the API, or trigger CI jobs when a new article appears.
• Home Automation – Use webhooks to notify smart speakers or lights when a breaking news item is posted.

Advantages

• Zero‑Cost Licensing – Completely free and open source under MIT, allowing unrestricted commercial use.
• Performance & Lightness – Minimal