Deploying JARR

Introduction

JARR (Just Another RSS Reader) is a web-based news aggregator and reader that lets you follow your favorite websites, blogs, and podcasts in one centralized location. As a fork of Newspipe, JARR provides a modern interface for consuming RSS and Atom feeds with intelligent article clustering and organization features.

Built with Python and React, JARR runs as a multi-container application with a JavaScript frontend, a Python API backend, and a Celery worker for background feed processing. The architecture enables efficient feed refreshing and article clustering without impacting the user interface.

Key highlights of JARR:

• Feed Aggregation: Subscribe to RSS and Atom feeds from any website
• Article Clustering: Intelligent grouping of related articles
• Modern Interface: Clean React-based web interface
• Background Processing: Asynchronous feed updates via Celery workers
• Feed Categories: Organize feeds into custom categories
• Read Tracking: Mark articles as read/unread with sync across devices
• Keyboard Shortcuts: Navigate efficiently with keyboard commands
• Mobile Friendly: Responsive design for mobile devices
• OPML Import/Export: Easy migration from other readers
• Open Source: Actively developed with regular updates

This guide walks through deploying JARR on Klutch.sh using Docker, configuring the required services, and setting up the application for daily news consumption.

Why Deploy JARR on Klutch.sh

Deploying JARR on Klutch.sh provides several advantages for self-hosted news reading:

Simplified Deployment: Klutch.sh handles the Docker container orchestration, deploying JARR’s components without complex configuration.

Persistent Storage: Attach persistent volumes for your database. Your subscriptions, read states, and preferences survive restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access from anywhere.

GitHub Integration: Connect your configuration repository for automated deployments.

Scalable Resources: Allocate CPU and memory based on the number of feeds you follow.

Environment Variable Management: Securely store database credentials and API secrets.

Custom Domains: Assign a custom domain for your personal news reader.

Always-On Availability: Your news feeds update and remain accessible 24/7.

Prerequisites

Before deploying JARR on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your JARR configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) A custom domain for your JARR instance

Understanding JARR Architecture

JARR runs as multiple interconnected services:

Frontend: React-based JavaScript application serving the user interface.

API Backend: Python Flask application handling data operations and authentication.

Celery Worker: Background task processor that refreshes feeds and clusters articles.

RabbitMQ: Message queue connecting the API to the worker for task distribution.

PostgreSQL: Database storing feeds, articles, user accounts, and preferences.

Preparing Your Repository

To deploy JARR on Klutch.sh, create a GitHub repository with your configuration.

Repository Structure

jarr-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for the JARR application:

FROM jaesivsm/jarr:latest

# Set environment variables
ENV FLASK_ENV=production
ENV JARR_CONFIG=/app/conf/jarr.json

# Expose the web interface port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8080/api/v2/status || exit 1

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
JARR_SECRET_KEY	Yes	-	Secret key for session signing
JARR_DATABASE_URL	Yes	-	PostgreSQL connection URL
JARR_BROKER_URL	Yes	-	RabbitMQ connection URL
JARR_ADMIN_EMAIL	No	-	Admin user email
JARR_ADMIN_PASSWORD	No	-	Admin user password
JARR_FEED_REFRESH_INTERVAL	No	300	Feed refresh interval in seconds

Deploying JARR on Klutch.sh

JARR requires multiple services. Follow these steps to deploy:

Generate a Secret Key

Generate a secure secret key:

python -c "import secrets; print(secrets.token_hex(32))"

Or use OpenSSL:

openssl rand -hex 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial JARR deployment configuration"
git remote add origin https://github.com/yourusername/jarr-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “jarr” or “news-reader”.

Deploy PostgreSQL

Deploy a PostgreSQL instance first. Note the connection details for the JARR configuration.

Deploy RabbitMQ

Deploy a RabbitMQ instance for the message queue. Note the connection URL.

Create a New App for JARR

Within your project, create a new app for JARR:

1. Connect your GitHub repository
2. Select the repository containing your Dockerfile
3. Configure HTTP traffic on port 8080

Set Environment Variables

Configure the required environment variables:

Variable	Value
JARR_SECRET_KEY	Your generated secret key
JARR_DATABASE_URL	postgresql://user:pass@postgres-host:5432/jarr
JARR_BROKER_URL	amqp://user:pass@rabbitmq-host:5672/
JARR_ADMIN_EMAIL	admin@example.com
JARR_ADMIN_PASSWORD	Your secure admin password

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
/app/data	5 GB	Application data and cache

Deploy Your Application

Click Deploy to start the build process.

Deploy the Worker

Create a second app for the Celery worker using the same repository but with a different startup command configured via environment variables.

Access JARR

Once deployment completes, access your JARR instance at https://your-app-name.klutch.sh.

Initial Configuration

Creating an Account

After deployment:

1. Navigate to your JARR instance
2. Click “Register” to create an account
3. Enter your email and password
4. Verify your account if email verification is enabled

Adding Your First Feeds

Subscribe to RSS feeds:

1. Click the ”+” button or “Add Feed”
2. Enter the feed URL (e.g., https://example.com/rss)
3. JARR will auto-discover and add the feed
4. Assign to a category if desired

Importing from Other Readers

Migrate your subscriptions:

1. Export OPML from your previous reader
2. Navigate to Settings > Import
3. Upload your OPML file
4. JARR will add all feeds and categories

Managing Feeds

Organizing Categories

Create categories for organization:

1. Navigate to Settings > Categories
2. Create categories like “News”, “Tech”, “Blogs”
3. Drag and drop feeds between categories
4. Set category-specific refresh intervals

Feed Settings

Configure individual feeds:

1. Click the settings icon on a feed
2. Set custom refresh interval
3. Configure filtering rules
4. Enable/disable clustering
5. Set notification preferences

Keyboard Shortcuts

Navigate efficiently:

Shortcut	Action
j / k	Next / previous article
n / p	Next / previous feed
o	Open article
m	Mark as read/unread
s	Star article
r	Refresh current feed

Article Clustering

How Clustering Works

JARR groups related articles:

• Articles about the same topic from different sources
• Reduces duplicate reading
• Shows different perspectives

Configuring Clustering

Adjust clustering settings:

1. Navigate to Settings > Clustering
2. Set similarity threshold
3. Choose clustering timeframe
4. Configure per-category settings

Production Best Practices

Security Recommendations

• Secret Key: Use a cryptographically secure secret key
• Database Security: Use strong passwords and restrict access
• HTTPS Only: Ensure all traffic uses HTTPS
• User Registration: Disable public registration if personal use

Performance Optimization

• Feed Limits: Limit the number of feeds if performance suffers
• Refresh Intervals: Don’t refresh too frequently
• Database Maintenance: Periodically clean old articles
• Worker Scaling: Add workers for many feeds

Backup Strategy

1. Database Backups: Regular PostgreSQL dumps
2. OPML Export: Periodically export feed subscriptions
3. Configuration: Back up environment settings

Troubleshooting Common Issues

Feeds Not Updating

Symptoms: New articles not appearing.

Solutions:

• Check worker container is running
• Verify RabbitMQ connectivity
• Review worker logs for errors
• Check feed URL is still valid

Authentication Issues

Symptoms: Can’t log in or session expires quickly.

Solutions:

• Verify SECRET_KEY is set correctly
• Check database connectivity
• Clear browser cookies

Slow Performance

Symptoms: Interface is sluggish.

Solutions:

• Reduce number of articles retained
• Optimize database queries
• Scale up container resources
• Check for database connection issues

Additional Resources

• JARR GitHub Repository
• JARR Wiki
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying JARR on Klutch.sh gives you a self-hosted news aggregator with intelligent article clustering and a modern interface. The combination of JARR’s powerful feed management and Klutch.sh’s container orchestration means you can focus on reading instead of infrastructure.

With support for OPML import, keyboard navigation, and background feed processing, JARR on Klutch.sh provides everything needed for a personalized news reading experience under your control.