Tiny Tiny RSS

Tiny Tiny RSS (tt‑rss) is a self‑hosted, web‑based feed aggregator that turns any modern browser into a lightweight RSS/Atom reader. From a developer’s perspective, it is essentially a PHP application that exposes a rich JSON API for programmatic consumption and offers a plugin architecture that can be extended with custom PHP, JavaScript, or even external services. The core engine runs on a LAMP stack (Linux/Apache/Nginx, MySQL/MariaDB, PHP 8+), but the project’s Docker images make it trivial to deploy in containerised environments or Kubernetes clusters. The application is released under GPLv3, which encourages community contributions while ensuring that any derivative work remains open source.

Technical Stack & Architecture

• Backend: PHP 8.x, leveraging procedural code with a modular plugin system. The core is split into inc/ modules that handle authentication, feed fetching, and article storage.
• Database: MySQL/MariaDB is the default; SQLite support is available for lightweight deployments. The schema is normalized with tables for feeds, entries, tags, and user preferences.
• Front‑end: Vanilla JavaScript with optional jQuery for legacy plugins. The UI is a single‑page application that communicates with the backend via AJAX, using the built‑in JSON API for CRUD operations on feeds and entries.
• Background Workers: Feed fetching is performed by a cron‑driven PHP script (fetcher.php) that can be run on the host or in a Docker container. The worker supports parallel fetching via --threads and respects feed‑specific update intervals.
• Containerization: Official Docker images expose environment variables for database credentials, SSL termination, and plugin mounting. A docker-compose.yml example is included in the repo for quick start.

Core Capabilities & APIs

• Feed Management: Import/export via OPML, bulk add/edit, and per‑feed update schedules.
• Article Handling: Deduplication (including perceptual hashing for images), full‑text extraction via Readability.js, and podcast support with metadata parsing.
• Filtering & Tagging: Server‑side filters written in a simple expression language, plus tag propagation across feeds.
• JSON API: Endpoints for authentication (/api/auth), feed operations (/api/feeds/*), entry queries (/api/entries*), and user settings. The API follows RESTful conventions with token‑based authentication.
• Webhooks & Plugins: A plugin system that can hook into events such as on_new_entry, on_fetch_start, and on_fetch_end. Plugins can be pure PHP, JavaScript, or external microservices invoked via HTTP. Built‑in plugins cover social media sharing, custom themes, and full‑text search.

Deployment & Infrastructure

• Self‑Hosting: Requires a web server (Apache or Nginx) with PHP 8+ and a relational database. The Docker images simplify deployment by bundling all dependencies.
• Scalability: While the core is designed for single‑user or small team use, scaling horizontally is possible by running multiple worker containers behind a load balancer and sharing the same database. The stateless nature of the API allows for easy horizontal scaling of the web tier.
• Containerization: The Docker image is built on php:fpm with optional nginx or apache. Volume mounts expose the plugin directory, themes, and configuration files. Kubernetes manifests are available in community forks.

Integration & Extensibility

• Plugin Ecosystem: Over 70 community plugins are available, ranging from social media integrations to custom authentication providers. Developers can write their own by implementing the plugin interface in PHP.
• API Hooks: The JSON API can be consumed by external services (e.g., mobile clients, chat bots). Webhooks allow integration with CI/CD pipelines or notification systems.
• Custom Themes: The UI can be overridden by providing CSS/JS overrides in the themes directory, enabling brand‑specific look and feel without touching core code.

Developer Experience

• Documentation: The README provides a high‑level overview; deeper documentation lives in the docs/ folder and the GitHub wiki. API reference is auto‑generated from PHPDoc comments.
• Community: Active GitHub discussions and issue trackers facilitate quick support. The project follows a continuous‑integration model, so the main branch is always stable.
• Testing: PHPUnit tests cover core logic, and CI pipelines run on every push. Developers can contribute by adding new unit tests for plugins or core features.

Use Cases

1. Personal Feed Hub: Deploy on a home server to keep all news, blogs, and podcasts in one place with full privacy.
2. Enterprise Knowledge Base: Use the API to pull feeds into internal dashboards or Slack channels, leveraging custom filters and tags.
3. Mobile‑First Development: Build a lightweight Android or iOS client that consumes the JSON API, while hosting tt‑rss on a Docker Swarm for reliability.
4. Open‑Source Projects: Host project release notes, issue trackers, and community blogs as RSS feeds for developers to consume programmatically.

Advantages Over Alternatives

• Open‑Source & GPLv3: No vendor lock‑in; can be forked or extended freely.
• **Fine‑Grained Control