Skip to content

dsh2dsh/miniflux

 
 

Repository files navigation

Miniflux 2

Miniflux is a minimalist and opinionated feed reader. It's simple, fast, lightweight and super easy to install.

Official website: https://miniflux.app

This project is an opinionated fork of Miniflux.

Breaking changes!!!

  • The database schema is incompatible with the upstream.

    Actually the database migration works fine from version 2.2.8, but not from later versions. So better use a new database for this fork.

Changes from upstream:

  • Google Reader API applies user's Entry sorting as default sort direction.

    The upstream uses hardcoded desc, if a reader didn't request specific sort direction, like Read You does at this moment. And entries always returned ordered newest first.

  • Refactor and simplify config parser.

    Use env and godotenv for parsing config and env variables. Validate it using validator.

  • Add LOG_FORMAT=human.

    It logs something like:

    2025/04/20 16:02:00 INFO Starting HTTP server listen_address=127.0.0.1:8080
    

    instead of

    time=2025-04-20T16:02:00.561+02:00 level=INFO msg="Starting HTTP server" listen_address=127.0.0.1:8080
    
  • Automatically reopen log file(s) on rotation.

  • Multiple log files.

    With configuration like this

    LOG_0_FILE=stderr
    LOG_0_FORMAT=human
    LOG_0_LEVEL=warning
    
    LOG_1_FILE=/var/log/miniflux/miniflux.log
    LOG_1_FORMAT=human
    LOG_1_DATE_TIME=true
    LOG_1_LEVEL=info
    

    all errors and warnings will be logged to both stderr and /var/log/miniflux/miniflux.log. Info messages will be logged to miniflux.log only.

    Any error from second logger will be logged by first logger. Errors from first logger are ignored.

  • Refactor CLI.

    Use cobra for parsing flags and args:

    $ miniflux -h
    Miniflux is a minimalist and opinionated feed reader.
    
    Usage:
      miniflux [flags]
      miniflux [command]
    
    Available Commands:
      completion               Generate the autocompletion script for the specified shell
      config-dump              Print parsed configuration values
      create-admin             Create an admin user from an interactive terminal
      export-user-feeds        Export user feeds
      flush-sessions           Flush all sessions (disconnect users)
      healthcheck              Perform a health check on the given endpoint
      help                     Help about any command
      info                     Show build information
      migrate                  Run SQL migrations
      refresh-feeds            Refresh a batch of feeds and exit
      reset-feed-errors        Clear all feed errors for all users
      reset-feed-next-check-at Reset the next check time for all feeds
      reset-password           Reset user password
      run-cleanup-tasks        Run cleanup tasks (delete old sessions and archives old entries)
    
    Flags:
      -c, --config-file string   Path to configuration file
          --config-yaml string   Path to YAML configuration file
      -d, --debug                Show debug logs
      -h, --help                 help for miniflux
      -v, --version              version for miniflux
    
    Use "miniflux [command] --help" for more information about a command.
    
  • Refactor storage and switch to pgx

    DATABASE_URL have additional variables for pool configuration:

    pool_max_conn_idle_time: duration string (default 30 minutes)
    pool_health_check_period: duration string (default 1 minute)
    pool_max_conn_lifetime_jitter: duration string (default 0)
    

    See ParseConfig for details.

    Don't specify pool_max_conns, pool_min_conns and pool_max_conn_lifetime, because config variables DATABASE_MAX_CONNS, DATABASE_MIN_CONNS and DATABASE_CONNECTION_LIFETIME overwrite it.

    DATABASE_MAX_CONNS changed its default from 20 to the greater of 4 or runtime.NumCPU().

  • Optionally prefer site icon, instead of feed icon.

    New option PREFER_SITE_ICON=true configures miniflux always use auto-detected site icon, instead of icon found in feed description.

  • Limit max number of connections per server and rate of connections.

    By default the maximum is 8 connections per server. This limit can be changed by adding CONNECTIONS_PER_SERVER to the config, like

    CONNECTIONS_PER_SERVER=10
    

    which increases the limit to 10 connections per server.

    By default the maximum allowed rate is 10 requests per second per server. This limit can be changed by adding RATE_LIMIT_PER_SERVER to the config, which defines requests per second, like

    RATE_LIMIT_PER_SERVER=100
    

    which increases the limit to 100 requests per second or

    RATE_LIMIT_PER_SERVER=0.5
    

    which decreases the limit to 1 request per 2 seconds.

    Connection limits also can be configured per host using YAML config like:

    host_limits:
      "localhost":
        connections: 3
        rate: 100
      "a.example.com":
        rate: 15
      "b.example.com":
        connections: 5
      "example.com":
        rate: 1

    Any of connections or rate is optional, but not both of them. If any of them is not specified, value from CONNECTIONS_PER_SERVER or RATE_LIMIT_PER_SERVER is using.

    To use this config, miniflux has new CLI flag --config-yaml.

  • Changed a little how article items looks like.

    Light theme: Light theme

    Dark theme: Dark theme

  • Republished entries marked as unread.

  • Custom comments URL per feed.

    Any feed can be configured with custom comments URL instead of feed's comment URL via edit feed UI. The new setting expected to be a templated string like: {{ .URL }}/comments/. This example appends /comments/ to entry URL and use it as comments URL of this entry. As a shortcut, if the template begins with / it directly appends to entry URL, like in previous example.

    The template can use function replace like:

    {{ replace .URL "/clanek/" "/diskuze/" }}

    which returns entry URL, where first substring /clanek/ replaced by /diskuze/.

    Also .CommentsURL can be used instead of .URL, which'll return original comments URL modified by the template.

  • Click on comments URL mark this entry as read.

    If mark entries as read when viewed enabled in user settings.

  • Mark entries as read when scrolled.

    This new option is disabled by default and can be enabled in user settings.

  • Don't trust HTTP headers X-Forwarded-For and X-Real-IP by default.

    Parse them only if request is from one of configured trusted proxies. By default 127.0.0.1 is the only trusted IP address. Can be changed with something like

    TRUSTED_PROXIES=127.0.0.1,192.168.0.1
    
  • Option to remove inactive sessions faster.

    By default inactive sessions removed after 10 days. It can be changed with

    CLEANUP_INACTIVE_SESSIONS_DAYS=30
    

    This this configuration inactive sessions will be removed after 30 days.

  • Naive deduplication of feed entries.

Features

Feed Reader

  • Supported feed formats: Atom 0.3/1.0, RSS 1.0/2.0, and JSON Feed 1.0/1.1.
  • OPML file import/export and URL import.
  • Supports multiple attachments (podcasts, videos, music, and images enclosures).
  • Plays videos from YouTube directly inside Miniflux.
  • Organizes articles using categories and bookmarks.
  • Share individual articles publicly.
  • Fetches website icons (favicons).
  • Saves articles to third-party services.
  • Provides full-text search (powered by Postgres).
  • Available in 20 languages: Portuguese (Brazilian), Chinese (Simplified and Traditional), Dutch, English (US), Finnish, French, German, Greek, Hindi, Indonesian, Italian, Japanese, Polish, Romanian, Russian, Taiwanese POJ, Ukrainian, Spanish, and Turkish.

Privacy and Security

  • Removes pixel trackers.
  • Strips tracking parameters from URLs (e.g., utm_source, utm_medium, utm_campaign, fbclid, etc.).
  • Retrieves original links when feeds are sourced from FeedBurner.
  • Opens external links with attributes rel="noopener noreferrer" referrerpolicy="no-referrer" for improved security.
  • Implements the HTTP header Referrer-Policy: no-referrer to prevent referrer leakage.
  • Provides a media proxy to avoid tracking and resolve mixed content warnings when using HTTPS.
  • Plays YouTube videos via the privacy-focused domain youtube-nocookie.com.
  • Supports alternative YouTube video players such as Invidious.
  • Blocks external JavaScript to prevent tracking and enhance security.
  • Sanitizes external content before rendering it.
  • Enforces a Content Security and a Trusted Types Policy to only application JavaScript and blocks inline scripts and styles.

Bot Protection Bypass Mechanisms

  • Optionally disable HTTP/2 to mitigate fingerprinting.
  • Allows configuration of a custom user agent.
  • Supports adding custom cookies for specific use cases.
  • Enables the use of proxies for enhanced privacy or bypassing restrictions.

Content Manipulation

  • Fetches the original article and extracts only the relevant content using a local Readability parser.
  • Allows custom scraper rules based on CSS selectors.
  • Supports custom rewriting rules for content manipulation.
  • Provides a regex filter to include or exclude articles based on specific patterns.
  • Optionally permits self-signed or invalid certificates (disabled by default).
  • Scrapes YouTube's website to retrieve video duration as read time or uses the YouTube API (disabled by default).

User Interface

  • Optimized stylesheet for readability.
  • Responsive design that adapts seamlessly to desktop, tablet, and mobile devices.
  • Minimalistic and distraction-free user interface.
  • No requirement to download an app from Apple App Store or Google Play Store.
  • Can be added directly to the home screen for quick access.
  • Supports a wide range of keyboard shortcuts for efficient navigation.
  • Optional touch gesture support for navigation on mobile devices.
  • Custom stylesheets and JavaScript to personalize the user interface to your preferences.
  • Themes:
    • Light (Sans-Serif)
    • Light (Serif)
    • Dark (Sans-Serif)
    • Dark (Serif)
    • System (Sans-Serif) – Automatically switches between Dark and Light themes based on system preferences.
    • System (Serif)

Integrations

Authentication

  • Local username and password.
  • Passkeys (WebAuthn).
  • Google (OAuth2).
  • Generic OpenID Connect.
  • Reverse-Proxy authentication.

Technical Stuff

  • Written in Go (Golang).
  • Single binary compiled statically without dependency.
  • Works only with PostgreSQL.
  • Does not use any ORM or any complicated frameworks.
  • Uses modern vanilla JavaScript only when necessary.
  • All static files are bundled into the application binary using the Go embed package.
  • Supports the Systemd sd_notify protocol for process monitoring.
  • Configures HTTPS automatically with Let's Encrypt.
  • Allows the use of custom SSL certificates.
  • Supports HTTP/2 when TLS is enabled.
  • Updates feeds in the background using an internal scheduler or a traditional cron job.
  • Uses native lazy loading for images and iframes.
  • Compatible only with modern browsers.
  • Adheres to the Twelve-Factor App methodology.
  • Provides official Debian/RPM packages and pre-built binaries.
  • Publishes a Docker image to Docker Hub, GitHub Registry, and Quay.io Registry, with ARM architecture support.
  • Uses a limited amount of third-party go dependencies
  • Has a comprehensive testsuite, with both unit tests and integration tests.
  • Only uses a couple of MB of memory and a negligible amount of CPU, even with several hundreds of feeds.
  • Respects/sends Last-Modified, If-Modified-Since, If-None-Match, Cache-Control, Expires and ETags headers, and has a default polling interval of 1h.

Documentation

The Miniflux documentation is available here: https://miniflux.app/docs/ (Man page)

Screenshots

Default theme:

Default theme

Dark theme when using keyboard navigation:

Dark theme

Credits

About

An opinionated fork of minimalist and opinionated feed reader

Topics

Resources

License

Security policy

Stars

Watchers

Forks

Languages

  • Go 85.5%
  • HTML 8.4%
  • JavaScript 3.1%
  • CSS 1.8%
  • Roff 0.6%
  • Makefile 0.3%
  • Other 0.3%