Deploying Miniflux

Introduction

Miniflux is a minimalist and opinionated feed reader written in Go. Unlike feature-heavy alternatives, Miniflux focuses on simplicity and speed, providing a clean interface for reading RSS and Atom feeds without unnecessary distractions. The application is designed to be fast, secure, and respect user privacy.

Built as a single binary with PostgreSQL for storage, Miniflux is lightweight and efficient. The application offers a web interface, REST API, and integrations with popular services while maintaining its minimalist philosophy.

Key highlights of Miniflux:

Minimalist Design: Clean, distraction-free reading interface
Fast Performance: Written in Go for speed and efficiency
RSS/Atom Support: Subscribe to any RSS or Atom feed
Keyboard Navigation: Full keyboard shortcuts for power users
Feed Rules: Filter and organize content automatically
Reader View: Clean article view with original content
API Access: Full REST API for third-party integrations
Mobile Apps: Compatible with various mobile feed readers
Multi-User: Support for multiple accounts
Privacy Focused: No tracking, no analytics, no external requests
Open Source: Apache 2.0 licensed

This guide walks through deploying Miniflux on Klutch.sh using Docker, configuring persistent storage, and setting up your personal feed reader.

Why Deploy Miniflux on Klutch.sh

Deploying Miniflux on Klutch.sh provides several advantages for self-hosted feed reading:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Miniflux without complex orchestration. Push to GitHub, and your feed reader deploys automatically.

Persistent Storage: Attach persistent volumes for your database. Your feeds, articles, and reading history survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your feed reader.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your feed count and reading habits.

Custom Domains: Assign a custom domain for easy access from any device.

Always-On Availability: Your feed reader runs 24/7, continuously fetching new articles.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and containerization concepts
A PostgreSQL database (can be deployed on Klutch.sh)
(Optional) A custom domain for your feed reader

Preparing Your Repository

To deploy Miniflux on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM miniflux/miniflux:latest

# Set environment variables
ENV LISTEN_ADDR=0.0.0.0:8080
ENV RUN_MIGRATIONS=1
ENV CREATE_ADMIN=1

# Expose port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/healthcheck || exit 1

Environment Variables Reference

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`ADMIN_USERNAME`	Yes	-	Admin account username
`ADMIN_PASSWORD`	Yes	-	Admin account password
`RUN_MIGRATIONS`	No	0	Run database migrations on startup
`CREATE_ADMIN`	No	0	Create admin user on startup
`POLLING_FREQUENCY`	No	60	Feed refresh interval in minutes
`BATCH_SIZE`	No	100	Number of feeds to refresh per batch
`POLLING_SCHEDULER`	No	round_robin	Scheduler type
`CLEANUP_FREQUENCY_HOURS`	No	24	Hours between cleanup runs
`CLEANUP_ARCHIVE_READ_DAYS`	No	60	Days to keep read articles
`CLEANUP_ARCHIVE_UNREAD_DAYS`	No	180	Days to keep unread articles

Deploying on Klutch.sh

Set Up PostgreSQL

Deploy a PostgreSQL database on Klutch.sh or use an external provider. Note the connection URL in the format:

postgres://user:password@host:5432/database?sslmode=disable

Choose Admin Credentials

Decide on your admin username and a secure password.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Miniflux deployment configuration"
git remote add origin https://github.com/yourusername/miniflux-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 “miniflux” or “feed-reader”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Miniflux Dockerfile.

Configure HTTP Traffic

Miniflux serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8080

Set Environment Variables

Add the following environment variables:

Variable	Value
`DATABASE_URL`	Your PostgreSQL connection string
`ADMIN_USERNAME`	Your admin username
`ADMIN_PASSWORD`	Your admin password
`RUN_MIGRATIONS`	`1`
`CREATE_ADMIN`	`1`
`POLLING_FREQUENCY`	`60`

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Start the Miniflux container
Run database migrations
Create the admin user
Provision an HTTPS certificate

Access Miniflux

Once deployment completes, access your Miniflux instance at https://example-app.klutch.sh and log in with your admin credentials.

Initial Setup

Navigate to your Miniflux URL
Log in with your admin credentials
You’ll see the empty feed list

Adding Your First Feeds

Click Feeds > Add Subscription
Enter the feed URL or website URL
Miniflux will auto-discover the feed
Configure feed settings and submit

Importing from Other Readers

Migrate from another feed reader:

Export OPML from your current reader
In Miniflux, go to Settings > Import
Upload your OPML file
All feeds will be added automatically

Using Miniflux

Reading Interface

Navigate the clean reading interface:

Unread: All unread articles
Starred: Saved favorite articles
History: Previously read articles
Feeds: Browse by individual feed
Categories: Browse by category

Keyboard Shortcuts

Miniflux supports full keyboard navigation:

Key	Action
`g u`	Go to unread
`g s`	Go to starred
`g h`	Go to history
`g f`	Go to feeds
`j`	Next article
`k`	Previous article
`o`	Open article
`v`	Open original
`s`	Toggle star
`m`	Toggle read
`r`	Refresh feeds
`?`	Show shortcuts

Feed Management

Feed Settings

Configure individual feeds:

Custom title: Override the feed name
Category: Assign to a category
Fetch original content: Use reader view
Scraper rules: Custom content extraction
Rewrite rules: Modify content
Blocklist rules: Filter unwanted articles

Feed Rules

Create rules to automate organization:

# Mark articles with "ad" in title as read
title=~ad

# Star articles from specific author
author=~John

# Keep all articles from important feeds
keep_forever=1

Reader View

Enable fetching original content:

Edit the feed settings
Enable Fetch original content
Articles will show full content instead of excerpts

API and Integrations

REST API

Miniflux provides a full REST API:

# Get all feeds
curl -H "X-Auth-Token: YOUR_API_KEY" \
  https://your-miniflux.klutch.sh/v1/feeds

# Add a new feed
curl -X POST -H "X-Auth-Token: YOUR_API_KEY" \
  -d '{"feed_url":"https://example.com/feed.xml"}' \
  https://your-miniflux.klutch.sh/v1/feeds

Mobile Apps

Compatible mobile readers:

Reeder (iOS): Native Miniflux support
Unread (iOS): Via Fever API
FeedMe (Android): Via Google Reader API
NetNewsWire (iOS/macOS): Native support

Fever API

Enable Fever API for compatible apps:

Go to Settings > Integrations
Generate a Fever API password
Use your Miniflux URL with /fever/ endpoint

Third-Party Integrations

Connect with other services:

Pocket: Save articles for later
Instapaper: Archive articles
Wallabag: Self-hosted read-later
Pinboard: Bookmark articles
Telegram: Send articles to chat

Maintenance

Automatic Cleanup

Miniflux automatically cleans old articles:

Read articles removed after 60 days (configurable)
Unread articles removed after 180 days (configurable)
Starred articles kept indefinitely

Manual Operations

Perform maintenance tasks:

Refresh All: Force refresh all feeds
Mark All Read: Clear unread count
Cleanup: Run cleanup manually

Troubleshooting

Feeds Not Updating

Check feed URL is accessible
Verify polling frequency settings
Review error count in feed settings
Try manual refresh

Connection Errors

Verify DATABASE_URL is correct
Check PostgreSQL is accessible
Review container logs

Missing Articles

Check cleanup settings
Verify fetch original content setting
Review feed blocklist rules

Additional Resources

Conclusion

Deploying Miniflux on Klutch.sh gives you a fast, minimalist feed reader that respects your privacy and focuses on what matters: reading content. With its clean interface, keyboard navigation, and powerful API, Miniflux provides an efficient way to stay informed without distractions.

The combination of Miniflux’s lightweight architecture and Klutch.sh’s reliable infrastructure ensures your feed reader runs efficiently 24/7. Whether you follow a handful of blogs or hundreds of feeds, Miniflux on Klutch.sh delivers a streamlined reading experience that you fully control.