RSSPipe 🚀

Modern, High-Performance RSS Information Gateway & Distraction-Free Reader

RSSPipe is a single-user, self-hosted RSS information gateway designed to replace traditional feeds readers with an elegant, ultra-fast, and distraction-free reading experience. Built with a robust Go backend and a modern React PWA interface.

---

✨ Key Features

• 🖥️ Reeder 4 Minimal 3-Pane View: Designed for desktop power users with collapsible navigation sidebar, dense article list, and distraction-free reading canvas.
• 📱 Xiaohongshu-Style Masonry Waterfall: Designed for mobile and media-rich browsing with adaptive masonry columns, category filter chips, and full-screen post reader.
• ⚡ High-Speed Crawler & Engine: Concurrent worker pool crawler in Go with per-feed polling intervals, custom timeouts, and HTTP conditional caching (ETag / Last-Modified 304).
• 🔒 Single-User Security & Auth: JWT-based session security and bcrypt hashing to secure access over the public internet.
• 📁 OPML 2.0 Import & Export: Effortless migration from Miniflux, Feedly, Inoreader, NetNewsWire, or Reeder.
• 🔗 Standalone Article Sharing: Instant public HTML snapshot sharing (/share/{uuid}.html) for individual articles.
• ⌨️ Keyboard Navigation: Complete single-key shortcut navigation (j/k next/previous, m mark read, s star, e archive, v view original, [ sidebar toggle).
• 💾 Local State & Reading Persistence: Restores exact view modes, filter selections, active feeds, and reading positions upon page refresh.

---

🛠️ Architecture & Tech Stack

   ┌─────────────────────────────────────────────────────────┐
   │                  React 18 PWA Frontend                  │
   │      (Vite + TypeScript + Lucide + Modern CSS)          │
   └──────────────────────────┬──────────────────────────────┘
                              │ REST API + Static Asset Serving
   ┌──────────────────────────▼──────────────────────────────┐
   │                   Go 1.22 HTTP Server                   │
   │               (Chi Router + JWT Auth)                   │
   ├──────────────────────────┬──────────────────────────────┤
   │    Background Crawler    │      SQLite Engine (WAL)     │
   │ (Worker Pool + Parser)   │  (modernc.org/sqlite Driver) │
   └──────────────────────────┴──────────────────────────────┘

• Backend: Go 1.22+, go-chi/chi, gofeed parser, golang-jwt/jwt.
• Database: Embedded SQLite with WAL mode (modernc.org/sqlite pure Go driver, no CGO required).
• Frontend: React 18, TypeScript, Vite, CSS custom properties.

---

🚀 Quickstart

Option 1: Run with Docker Compose

# Clone the repository
git clone https://git.pengzhan.dev/haopengzhan/rsspipe.git
cd rsspipe

# Start RSSPipe
docker compose up -d

Visit http://localhost:8080. Default credentials:

• Username: admin
• Password: admin123456 (configurable via environment variables)

---

Option 2: Local Development Setup

Prerequisites

• Go 1.22+
• Node.js 18+ & npm

# Clone the repository
git clone https://git.pengzhan.dev/haopengzhan/rsspipe.git
cd rsspipe

# Build and start server using Makefile
make dev

Or build separately:

make build          # Compiles frontend bundle + backend binary into bin/rsspipe
./bin/rsspipe       # Runs production binary

The server binds to http://localhost:8080 and serves both the API endpoints and static frontend assets.

---

⚙️ Configuration & Environment Variables

Variable	Default	Description
PORT	8080	Server HTTP port
DB_PATH	./data/rsspipe.db	Path to SQLite database file
JWT_SECRET	(auto-generated)	32-byte secret key for signing JWT tokens
ADMIN_USERNAME	admin	Initial default administrator username
ADMIN_PASSWORD	admin123456	Initial default administrator password
CRAWLER_WORKERS	10	Number of concurrent fetch worker threads
CRAWLER_INTERVAL	15	Default background crawler interval (minutes)

---

⌨️ Keyboard Shortcuts

Shortcut	Action
j / k	Navigate to Next / Previous article
m	Toggle Read / Unread status
s	Toggle Starred status
e	Mark as read and advance to next
v	Open original article URL in new tab
[	Toggle left navigation sidebar
r	Trigger immediate refresh of feeds
a	Open "Add Subscription" modal
1	Switch to Desktop 3-Split View
2	Switch to Xiaohongshu Waterfall View
3	Switch to Settings & Management View
Shift + A	Mark all items in active view as read
?	Open keyboard shortcuts cheatsheet
Esc	Close any active modal dialog

---

🧪 Testing & Quality Automation

make check          # Run all quality checks (gofmt, go vet, tests, tsc, gitleaks)
make test           # Run backend Go unit tests
make lint           # Check formatting and run go vet
make format         # Auto-format all Go files

---

📄 License

MIT License. Free for personal and commercial self-hosted use.