feat: complete MVP setup with CI/CD, Makefile, docker, and backlog docs

2026-08-24 21:43:21 -07:00
parent 7a51931386
commit 4197d86626
20 changed files with 590 additions and 24 deletions
@@ -0,0 +1,140 @@
+# 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
+
+```bash
+# 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**
+
+```bash
+# 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:
+```bash
+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
+
+```bash
+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.