Deploying NewsBlur

Introduction

NewsBlur is a personal news reader that brings together the best of RSS reading with modern features like intelligence training, social sharing, and a beautiful reading experience. Originally a commercial service, NewsBlur is fully open source and can be self-hosted for complete control over your news consumption.

What sets NewsBlur apart is its intelligence trainer: as you read, you can train it to highlight stories you like and hide stories you don’t based on authors, topics, and sources. Over time, NewsBlur learns your preferences and surfaces the most relevant content first.

Key highlights of NewsBlur:

• Intelligence Training: Teach NewsBlur your preferences to filter and prioritize stories
• Original Site View: Read articles on the original website within NewsBlur
• Text View: Clean, distraction-free reading mode
• Story Sharing: Share stories with friends and followers
• Blurblogs: Public sharing pages for curated content
• Feed Statistics: Understand your reading habits
• Mobile Apps: Native iOS and Android applications
• Keyboard Shortcuts: Efficient navigation for power users
• OPML Import/Export: Standard feed list compatibility
• Open Source: Self-host for complete control

This guide walks through deploying NewsBlur on Klutch.sh using Docker.

Why Deploy NewsBlur on Klutch.sh

Deploying NewsBlur on Klutch.sh provides several advantages:

Data Ownership: Your reading history, preferences, and subscriptions stay on your own infrastructure.

Always Available: Access your news feeds from anywhere, anytime.

Simplified Deployment: Klutch.sh handles the complex multi-service architecture.

Persistent Storage: Your subscriptions and trained preferences persist across restarts.

HTTPS by Default: Secure access to your personal news reader.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• A PostgreSQL database
• A MongoDB database
• A Redis instance
• An Elasticsearch instance (optional, for search)
• Basic familiarity with Docker concepts

Understanding NewsBlur Architecture

NewsBlur consists of several components:

Django Application: Main web application handling user interface and API.

Feed Fetcher: Background worker that polls RSS feeds.

Task Queue: Celery workers for asynchronous processing.

PostgreSQL: Stores user data, subscriptions, and sharing information.

MongoDB: Stores feed content and stories.

Redis: Caching and session storage.

Elasticsearch: Full-text search (optional).

Note: Due to NewsBlur’s complex architecture with multiple services, self-hosting requires careful setup of all components.

Preparing Your Repository

Create a GitHub repository for your NewsBlur deployment.

Repository Structure

newsblur-deploy/
├── Dockerfile
├── docker-compose.yml
├── local_settings.py
└── .dockerignore

Creating the Dockerfile

FROM newsblur/newsblur:latest

# Environment configuration
ENV NEWSBLUR_DB_HOST=${POSTGRES_HOST}
ENV NEWSBLUR_DB_NAME=${POSTGRES_DB}
ENV NEWSBLUR_DB_USER=${POSTGRES_USER}
ENV NEWSBLUR_DB_PASSWORD=${POSTGRES_PASSWORD}
ENV MONGODB_HOST=${MONGO_HOST}
ENV REDIS_HOST=${REDIS_HOST}

# Copy custom settings
COPY local_settings.py /srv/newsblur/newsblur_web/local_settings.py

EXPOSE 8000

Local Settings Configuration

Create local_settings.py:

import os

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('POSTGRES_DB', 'newsblur'),
        'USER': os.environ.get('POSTGRES_USER', 'newsblur'),
        'PASSWORD': os.environ.get('POSTGRES_PASSWORD', ''),
        'HOST': os.environ.get('POSTGRES_HOST', 'localhost'),
        'PORT': '5432',
    }
}

MONGO_DB = {
    'host': os.environ.get('MONGO_HOST', 'localhost'),
    'port': 27017,
}

REDIS = {
    'host': os.environ.get('REDIS_HOST', 'localhost'),
    'port': 6379,
}

SECRET_KEY = os.environ.get('SECRET_KEY', 'change-this-secret-key')

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
.DS_Store

Deploying NewsBlur on Klutch.sh

Set Up Required Services

Before deploying NewsBlur, ensure you have:

• PostgreSQL database running
• MongoDB instance running
• Redis instance running

These can be managed services or self-hosted.

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a project named “newsblur” or “news-reader”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

NewsBlur serves its web interface over HTTP:

• Select HTTP as the traffic type
• Set the internal port to 8000

Set Environment Variables

Configure database connections:

Variable	Value
POSTGRES_HOST	Your PostgreSQL host
POSTGRES_DB	newsblur
POSTGRES_USER	Database username
POSTGRES_PASSWORD	Database password
MONGO_HOST	Your MongoDB host
REDIS_HOST	Your Redis host
SECRET_KEY	Secure random string

Attach Persistent Volumes

Configure storage:

Mount Path	Recommended Size	Purpose
/srv/newsblur/logs	2 GB	Application logs
/srv/newsblur/static	1 GB	Static assets

Deploy Your Application

Click Deploy to build and start your NewsBlur instance.

Run Database Migrations

After initial deployment, run migrations to set up the database schema.

Access NewsBlur

Visit https://your-app-name.klutch.sh to access your news reader.

Initial Setup

Creating Admin Account

Set up your administrator:

1. Access the Django admin
2. Create your user account
3. Configure admin permissions

Adding Your First Feeds

Subscribe to RSS feeds:

1. Click “Add Site” or use the keyboard shortcut
2. Enter feed URL or website URL
3. NewsBlur will discover the feed
4. Confirm subscription

Importing from Other Readers

Migrate existing subscriptions:

1. Export OPML from your current reader
2. Go to Settings > Import OPML
3. Upload your OPML file
4. Feeds are added to your account

Intelligence Training

Training Basics

Teach NewsBlur your preferences:

1. Open a story
2. Click the trainer icon
3. Like or dislike:
   • Author
   • Publisher
   • Tags
   • Title keywords

Training Effects

How training affects your reading:

• Green (Like): Stories show with green highlight
• Red (Dislike): Stories are hidden by default
• Neutral: Normal display

Focus Mode

Read only what matters:

1. Enable Focus mode
2. See only green-trained stories
3. Perfect for catching up quickly

Reading Experience

View Modes

Choose how to read:

• Feed View: Original content in list format
• Story View: Full story with clean formatting
• Original View: Embedded original website
• Text View: Extracted article text only

Keyboard Shortcuts

Efficient navigation:

• j/k - Next/previous story
• n/p - Next/previous unread
• o - Open original
• s - Save story
• r - Mark as read
• ? - Show all shortcuts

Story Actions

Interact with stories:

• Save for later
• Share to Blurblog
• Email story
• Send to read-later services

Social Features

Blurblog

Your public sharing page:

1. Share interesting stories
2. Add comments
3. Others can follow your Blurblog
4. Build curated content feeds

Following Friends

Social reading:

1. Find friends on NewsBlur
2. Follow their Blurblogs
3. See shared stories in River of News
4. Discover new content through friends

Feed Management

Organizing Feeds

Keep feeds organized:

1. Create folders for categories
2. Drag feeds into folders
3. Rename and reorder as needed

Feed Settings

Configure per-feed options:

• Notification settings
• Fetch frequency (premium)
• Feed address updates
• Statistics view

Muting Feeds

Temporarily hide feeds:

1. Right-click feed
2. Select “Mute”
3. Feed won’t show unread counts
4. Unmute when ready to read

Production Best Practices

Resource Planning

NewsBlur needs resources:

• Feed fetching is CPU/network intensive
• MongoDB needs sufficient storage
• Redis needs adequate memory
• Scale based on feed count

Feed Fetching

Optimize feed polling:

• Configure fetch intervals
• Respect feed update hints
• Handle error feeds gracefully
• Monitor fetch queue

Backup Strategy

Protect your data:

1. PostgreSQL backups (users, settings)
2. MongoDB backups (stories)
3. OPML export for feed list
4. Regular automated backups

Troubleshooting

Feeds Not Updating

• Check feed fetcher is running
• Verify feed URL is valid
• Check for fetch errors in admin
• Review feed statistics

Slow Performance

• Monitor database connections
• Check Redis memory usage
• Review Celery queue length
• Optimize MongoDB indexes

Login Issues

• Verify PostgreSQL connection
• Check session storage (Redis)
• Clear browser cookies
• Review authentication logs

Missing Stories

• Check MongoDB connectivity
• Verify feed is being fetched
• Review story retention settings
• Check for parsing errors

Simplified Alternative

Due to NewsBlur’s complexity, consider:

Hosted NewsBlur: newsblur.com offers affordable premium plans

Simpler Alternatives:

• FreshRSS (PHP, single container)
• Miniflux (Go, single container)
• Tiny Tiny RSS (PHP-based)

Additional Resources

• Official NewsBlur
• NewsBlur GitHub Repository
• NewsBlur FAQ
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying NewsBlur on Klutch.sh gives you a powerful, self-hosted news reader with unique intelligence training features. While the multi-service architecture requires more setup than simpler alternatives, the result is a sophisticated reading experience that learns your preferences.

For those willing to manage the complexity, NewsBlur provides an unmatched combination of feed reading, content filtering, and social features. Whether you’re following a few blogs or hundreds of feeds, NewsBlur helps you focus on the content that matters most.