glean

Glean 拾灵

English | 中文

[!IMPORTANT] Join our Discord to stay updated on the latest developments and get support.

This project is still in development and is not ready for production use.

A self-hosted RSS reader and personal knowledge management tool.

Glean (拾灵) helps information-heavy consumers efficiently manage their reading through intelligent RSS aggregation.

Features

Core Features

• 📰 RSS Subscription - Subscribe and organize RSS/Atom feeds with OPML import/export
• 📚 Smart Reading - Clean reading experience with content filtering
• 🔖 Read Later - Save articles for later reading with auto-cleanup
• 📁 Folders & Tags - Multi-level folders and tags for organization
• ⭐ Bookmarks - Save articles from feeds or external URLs
• 🔧 Background Sync - Automatic feed updates every 15 minutes
• 🔒 Self-hosted - Full data ownership with Docker deployment
• 🎨 Modern UI - Beautiful, responsive warm dark theme interface
• 👨‍💼 Admin Dashboard - User management and system monitoring

Planned Features (WIP)

• 🧠 Smart Recommendations - AI-powered preference learning and article scoring
• ⚙️ Rule Engine - Automated processing with Jinja2-style conditions
• 🤖 AI Features - Summary generation, auto-tagging, keyword extraction (BYOK)
• 📄 Full Content Fetch - Fetch complete article content for RSS summaries
• 🔌 Chrome Extension - One-click bookmarking from browser
• 📱 Mobile PWA - Progressive Web App for mobile devices

Quick Start

Using pgvector (Recommended)

Uses PostgreSQL's built-in pgvector extension — no extra infrastructure required:

# Download pgvector compose
curl -fsSL https://raw.githubusercontent.com/LeslieLeung/glean/main/docker-compose.pgvector.yml -o docker-compose.yml

# Start Glean
docker compose up -d

# Access:
# - Web App: http://localhost
# - Admin Dashboard: http://localhost:3001 (default: admin/Admin123!)

Default Admin Account: An admin account is automatically created with:

• Username: admin
• Password: Admin123!
• ⚠️ Change this password in production!

Using Milvus

For deployments that prefer a dedicated Milvus vector database:

# Download docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/LeslieLeung/glean/main/docker-compose.yml -o docker-compose.yml

# Start Glean
docker compose up -d

# Access:
# - Web App: http://localhost
# - Admin Dashboard: http://localhost:3001 (default: admin/Admin123!)

Customize Admin Account (Optional)

To use custom admin credentials instead of the defaults, create a .env file before starting:

# Set custom admin credentials in .env
cat > .env << EOF
ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourSecurePassword123!
SECRET_KEY=$(openssl rand -base64 32)
EOF

# Start services
docker compose up -d

To disable auto-creation and create admin manually:

# Disable auto-creation in .env
echo "CREATE_ADMIN=false" >> .env

# Start services
docker compose up -d

# Create admin manually
docker exec -it glean-backend /app/scripts/create-admin-docker.sh

Configuration

For production, customize your deployment with environment variables. Download the example file:

curl -fsSL https://raw.githubusercontent.com/LeslieLeung/glean/main/.env.example -o .env

Important settings to change:

Variable	Description	Default
SECRET_KEY	JWT signing key	Must change in production!
POSTGRES_PASSWORD	Database password	glean (Change in production!)
ADMIN_PASSWORD	Admin password	Admin123! (Change!)
WEB_PORT	Web interface port	80
ADMIN_PORT	Admin dashboard port	3001
CREATE_ADMIN	Auto-create admin	true (set false to disable)

For all configuration options, see .env.example.

Docker Images

Pre-built images are available on GitHub Container Registry:

• ghcr.io/leslieleung/glean-backend:latest - API server & worker
• ghcr.io/leslieleung/glean-web:latest - Web frontend
• ghcr.io/leslieleung/glean-admin:latest - Admin dashboard

Supported architectures: linux/amd64, linux/arm64

Testing Pre-release Versions

Want to test upcoming features? Use pre-release versions (alpha/beta/rc):

Method 1: Using environment variable (recommended)

# Set the IMAGE_TAG in .env file
echo "IMAGE_TAG=v0.3.0-alpha.1" >> .env

# Or export it directly
export IMAGE_TAG=v0.3.0-alpha.1

# Start with pre-release images
docker compose up -d

Method 2: Inline environment variable

IMAGE_TAG=v0.3.0-alpha.1 docker compose up -d

Note: Pre-release versions are for testing only. They won't trigger auto-updates for Electron apps and are not recommended for production use.

See available pre-release versions on the Releases page.

Deployment

Both deployments include the same core services:

• Web App (port 80) - Main user interface
• Admin Dashboard (port 3001) - User management and system monitoring
• Backend API - FastAPI server
• Worker - Background task processor (feed fetching, cleanup)
• PostgreSQL - Database
• Redis - Task queue

The difference is the vector backend: docker-compose.pgvector.yml uses PostgreSQL's pgvector extension (recommended), while docker-compose.yml uses a dedicated Milvus vector database.

For detailed deployment instructions and configuration, see DEPLOY.md.

Already running Milvus? Follow the pgvector migration guide to migrate with one script, including backup, restore, resumable execution, and rollback.

Tech Stack

Backend:

• Python 3.11+ / FastAPI / SQLAlchemy 2.0
• PostgreSQL / Redis / arq (task queue)

Frontend:

• React 18 / TypeScript / Vite
• Tailwind CSS / Zustand / TanStack Query

Development

See DEVELOPMENT.md for complete development setup instructions.

Quick start:

# Clone and setup
git clone https://github.com/LeslieLeung/glean.git
cd glean
npm install

# Start infrastructure
make up

# Initialize database (first time only)
make db-upgrade

# Install pre-commit hooks (optional but recommended)
make pre-commit-install

# Start all services
make dev-all

# Access:
# - Web: http://localhost:3000
# - Admin: http://localhost:3001
# - API Docs: http://localhost:8000/api/docs

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality:

# Install hooks (one-time setup)
make pre-commit-install

# Run hooks manually on all files
make pre-commit-run

# Uninstall hooks (if needed)
make pre-commit-uninstall

Hooks automatically run on commit and check:

• Backend: ruff format, ruff linter, pyright type checking
• Frontend: ESLint, Prettier formatting
• General: trailing whitespace, file endings, YAML/JSON/TOML validation

Roadmap

Phase	Status	Features
Phase 1: MVP	✅ Done	User system, RSS subscription, reader, admin dashboard
Phase 2: Organization	✅ Done	Bookmarks, folders, tags, read later
Phase 3: Preferences	✅ Done	Embedding pipeline, preference learning, smart recommendations
Phase 4: Rules	📋 Planned	Rule engine, Jinja2 conditions, automated actions
Phase 5: AI	📋 Planned	AI summaries, auto-tagging, keyword extraction, BYOK support
Phase 6: Extensions	📋 Planned	Chrome extension, PWA, web snapshots

Documentation

• Development Guide - Set up your development environment
• Deployment Guide - Production deployment details

Contributing

Contributions are welcome! Please read our Development Guide first.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a Pull Request

License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.