{"id":34383746,"url":"https://github.com/LeslieLeung/glean","last_synced_at":"2025-12-23T20:00:38.614Z","repository":{"id":326947235,"uuid":"1107212497","full_name":"LeslieLeung/glean","owner":"LeslieLeung","description":"A self-hosted RSS reader and personal knowledge management tool.","archived":false,"fork":false,"pushed_at":"2025-12-19T22:16:45.000Z","size":19984,"stargazers_count":546,"open_issues_count":19,"forks_count":38,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-21T02:59:49.332Z","etag":null,"topics":["rss","rss-reader"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LeslieLeung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-30T19:39:05.000Z","updated_at":"2025-12-20T13:54:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LeslieLeung/glean","commit_stats":null,"previous_names":["leslieleung/glean"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/LeslieLeung/glean","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeslieLeung%2Fglean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeslieLeung%2Fglean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeslieLeung%2Fglean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeslieLeung%2Fglean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LeslieLeung","download_url":"https://codeload.github.com/LeslieLeung/glean/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeslieLeung%2Fglean/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27985092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-23T02:00:07.087Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rss","rss-reader"],"created_at":"2025-12-18T17:00:49.962Z","updated_at":"2025-12-23T20:00:38.605Z","avatar_url":"https://github.com/LeslieLeung.png","language":"TypeScript","readme":"# Glean 拾灵\n\n**[English](./README.md)** | **[中文](./README.zh-CN.md)**\n\n\u003e [!IMPORTANT]\n\u003e Join our [Discord](https://discord.gg/KMKC4sRVSJ) to stay updated on the latest developments and get support.\n\u003e\n\u003e This project is still in development and is not ready for production use.\n\nA self-hosted RSS reader and personal knowledge management tool.\n\n\u003e **Glean** (拾灵) helps information-heavy consumers efficiently manage their reading through intelligent RSS aggregation.\n\n![Glean](asset/Screenshot.png)\n\n## Features\n\n### Core Features\n- 📰 **RSS Subscription** - Subscribe and organize RSS/Atom feeds with OPML import/export\n- 📚 **Smart Reading** - Clean reading experience with content filtering\n- 🔖 **Read Later** - Save articles for later reading with auto-cleanup\n- 📁 **Folders \u0026 Tags** - Multi-level folders and tags for organization\n- ⭐ **Bookmarks** - Save articles from feeds or external URLs\n- 🔧 **Background Sync** - Automatic feed updates every 15 minutes\n- 🔒 **Self-hosted** - Full data ownership with Docker deployment\n- 🎨 **Modern UI** - Beautiful, responsive warm dark theme interface\n- 👨‍💼 **Admin Dashboard** - User management and system monitoring\n\n### Planned Features (WIP)\n- 🧠 **Smart Recommendations** - AI-powered preference learning and article scoring\n- ⚙️ **Rule Engine** - Automated processing with Jinja2-style conditions\n- 🤖 **AI Features** - Summary generation, auto-tagging, keyword extraction (BYOK)\n- 📄 **Full Content Fetch** - Fetch complete article content for RSS summaries\n- 🔌 **Chrome Extension** - One-click bookmarking from browser\n- 📱 **Mobile PWA** - Progressive Web App for mobile devices\n\n## Quick Start\n\n### One-Command Deployment\n\n```bash\n# Download docker-compose.yml\ncurl -fsSL https://raw.githubusercontent.com/LeslieLeung/glean/main/docker-compose.yml -o docker-compose.yml\n\n# Start Glean (full deployment with Milvus)\ndocker compose up -d\n\n# Access:\n# - Web App: http://localhost\n# - Admin Dashboard: http://localhost:3001\n```\n\n**Lite Deployment** (without Milvus, if you don't need Phase 3 features):\n\n```bash\n# Download lite version\ncurl -fsSL https://raw.githubusercontent.com/LeslieLeung/glean/main/docker-compose.lite.yml -o docker-compose.yml\n\n# Start Glean\ndocker compose up -d\n```\n\n### Create Admin Account\n\nAfter first startup, create an admin account to access the dashboard:\n\n```bash\n# Generate random password (recommended)\ndocker exec -it glean-backend /app/scripts/create-admin-docker.sh\n\n# Or specify custom credentials\ndocker exec -it glean-backend /app/scripts/create-admin-docker.sh myusername MySecurePass123!\n```\n\nAlternatively, create admin on first startup using environment variables:\n\n```bash\n# Set admin credentials in .env\nCREATE_ADMIN=true\nADMIN_USERNAME=admin\nADMIN_PASSWORD=YourSecurePassword123!\n\n# Start services\ndocker compose up -d\n\n# Check logs to confirm\ndocker compose logs backend | grep \"Admin Account Created\"\n```\n\n## Configuration\n\nFor production, customize your deployment with environment variables. Download the example file:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/LeslieLeung/glean/main/.env.example -o .env\n```\n\n**Important settings to change:**\n\n| Variable            | Description          | Default                              |\n| ------------------- | -------------------- | ------------------------------------ |\n| `SECRET_KEY`        | JWT signing key      | **Must change in production!**       |\n| `POSTGRES_PASSWORD` | Database password    | `glean` (**Change in production!**)  |\n| `WEB_PORT`          | Web interface port   | `80`                                 |\n| `ADMIN_PORT`        | Admin dashboard port | `3001`                               |\n| `CREATE_ADMIN`      | Auto-create admin    | `false` (set `true` for first start) |\n\nFor all configuration options, see [.env.example](.env.example).\n\n## Docker Images\n\nPre-built images are available on GitHub Container Registry:\n\n- `ghcr.io/leslieleung/glean-backend:latest` - API server \u0026 worker\n- `ghcr.io/leslieleung/glean-web:latest` - Web frontend\n- `ghcr.io/leslieleung/glean-admin:latest` - Admin dashboard\n\nSupported architectures: `linux/amd64`, `linux/arm64`\n\n### Testing Pre-release Versions\n\nWant to test upcoming features? Use pre-release versions (alpha/beta/rc):\n\n**Method 1: Using environment variable (recommended)**\n\n```bash\n# Set the IMAGE_TAG in .env file\necho \"IMAGE_TAG=v0.3.0-alpha.1\" \u003e\u003e .env\n\n# Or export it directly\nexport IMAGE_TAG=v0.3.0-alpha.1\n\n# Start with pre-release images\ndocker compose up -d\n```\n\n**Method 2: Inline environment variable**\n\n```bash\nIMAGE_TAG=v0.3.0-alpha.1 docker compose up -d\n```\n\n**Note**: Pre-release versions are for testing only. They won't trigger auto-updates for Electron apps and are not recommended for production use.\n\nSee available pre-release versions on the [Releases page](https://github.com/LeslieLeung/glean/releases).\n\n## Deployment\n\nThe default deployment includes all services (full version):\n- **Web App** (port 80) - Main user interface\n- **Admin Dashboard** (port 3001) - User management and system monitoring\n- **Backend API** - FastAPI server\n- **Worker** - Background task processor (feed fetching, cleanup)\n- **PostgreSQL** - Database\n- **Redis** - Task queue\n- **Milvus** - Vector database for smart recommendations and preference learning (Phase 3)\n\n**Lite deployment** (without Milvus) is also available using `docker-compose.lite.yml`.\n\nFor detailed deployment instructions and configuration, see [DEPLOY.md](DEPLOY.md).\n\n## Tech Stack\n\n**Backend:**\n- Python 3.11+ / FastAPI / SQLAlchemy 2.0\n- PostgreSQL / Redis / arq (task queue)\n\n**Frontend:**\n- React 18 / TypeScript / Vite\n- Tailwind CSS / Zustand / TanStack Query\n\n## Development\n\nSee **[DEVELOPMENT.md](./DEVELOPMENT.md)** for complete development setup instructions.\n\nQuick start:\n\n```bash\n# Clone and setup\ngit clone https://github.com/LeslieLeung/glean.git\ncd glean\nnpm install\n\n# Start infrastructure\nmake up\n\n# Initialize database (first time only)\nmake db-upgrade\n\n# Install pre-commit hooks (optional but recommended)\nmake pre-commit-install\n\n# Start all services\nmake dev-all\n\n# Access:\n# - Web: http://localhost:3000\n# - Admin: http://localhost:3001\n# - API Docs: http://localhost:8000/api/docs\n```\n\n### Pre-commit Hooks\n\nThe project uses pre-commit hooks to ensure code quality:\n\n```bash\n# Install hooks (one-time setup)\nmake pre-commit-install\n\n# Run hooks manually on all files\nmake pre-commit-run\n\n# Uninstall hooks (if needed)\nmake pre-commit-uninstall\n```\n\nHooks automatically run on commit and check:\n- Backend: ruff format, ruff linter, pyright type checking\n- Frontend: ESLint, Prettier formatting\n- General: trailing whitespace, file endings, YAML/JSON/TOML validation\n\n## Roadmap\n\n| Phase                     | Status    | Features                                                       |\n| ------------------------- | --------- | -------------------------------------------------------------- |\n| **Phase 1: MVP**          | ✅ Done    | User system, RSS subscription, reader, admin dashboard         |\n| **Phase 2: Organization** | ✅ Done    | Bookmarks, folders, tags, read later                           |\n| **Phase 3: Preferences**  | 🚧 WIP     | Embedding pipeline, preference learning, smart recommendations |\n| **Phase 4: Rules**        | 📋 Planned | Rule engine, Jinja2 conditions, automated actions              |\n| **Phase 5: AI**           | 📋 Planned | AI summaries, auto-tagging, keyword extraction, BYOK support   |\n| **Phase 6: Extensions**   | 📋 Planned | Chrome extension, PWA, web snapshots                           |\n\nSee **[Product Requirements](./docs/glean-prd-v1.2.md)** for detailed feature specifications.\n\n## Documentation\n\n- **[Development Guide](./DEVELOPMENT.md)** - Set up your development environment\n- **[Deployment Guide](./deploy/README.md)** - Production deployment details\n\n## Contributing\n\nContributions are welcome! Please read our [Development Guide](./DEVELOPMENT.md) first.\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and linting\n5. Submit a Pull Request\n\n## License\n\nThis project is licensed under the **AGPL-3.0 License** - see the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLeslieLeung%2Fglean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLeslieLeung%2Fglean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLeslieLeung%2Fglean/lists"}