How to Self-Host Miniflux with Docker Compose

What Is Miniflux?

Miniflux is an opinionated, minimalist RSS reader. Where FreshRSS gives you a feature-rich experience, Miniflux strips everything down to the essentials: subscribe to feeds, read articles, done. It’s written in Go, compiles to a single binary, uses PostgreSQL for storage, and has a clean web UI that loads instantly. Miniflux also supports the Google Reader API and Fever API for mobile app sync, and has built-in integrations with services like Pinboard, Instapaper, Wallabag, and Matrix.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 256 MB of free RAM
• 500 MB of free disk space
• A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  miniflux:
    image: miniflux/miniflux:2.2.18
    container_name: miniflux
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: "postgres://miniflux:change_this_strong_password@miniflux_db/miniflux?sslmode=disable"
      RUN_MIGRATIONS: "1"                # Auto-run database migrations on startup
      CREATE_ADMIN: "1"                  # Create admin user on first run
      ADMIN_USERNAME: "admin"            # Admin username — CHANGE THIS
      ADMIN_PASSWORD: "change_this_password"  # Admin password — CHANGE THIS
    depends_on:
      miniflux_db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "/usr/bin/miniflux", "-healthcheck", "auto"]
      interval: 30s
      timeout: 10s
      retries: 3

  miniflux_db:
    image: postgres:16-alpine
    container_name: miniflux_db
    restart: unless-stopped
    environment:
      POSTGRES_USER: miniflux
      POSTGRES_PASSWORD: change_this_strong_password    # Must match DATABASE_URL above
      POSTGRES_DB: miniflux
    volumes:
      - miniflux_db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U miniflux"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  miniflux_db:

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server-ip:8080 in your browser
2. Log in with the ADMIN_USERNAME and ADMIN_PASSWORD you set in the Compose file
3. After first login, remove CREATE_ADMIN and ADMIN_PASSWORD from your Compose file (they’re only needed once)
4. Start adding feeds via Feeds → Add Subscription

The hstore PostgreSQL extension is created automatically when RUN_MIGRATIONS=1 is set.

Configuration

Key Environment Variables

Variable	Default	Description
POLLING_FREQUENCY	60	Minutes between feed checks
BATCH_SIZE	100	Feeds fetched per polling cycle
CLEANUP_ARCHIVE_READ_DAYS	-1	Days to keep read articles (-1 = forever)
CLEANUP_ARCHIVE_UNREAD_DAYS	180	Days to keep unread articles
FETCH_YOUTUBE_WATCH_TIME	0	Fetch YouTube video durations
LISTEN_ADDR	0.0.0.0:8080	Bind address
BASE_URL	http://localhost	Public URL (set for reverse proxy)

API Access (Mobile Apps)

Miniflux supports the Google Reader API and Fever API:

• Google Reader API: https://your-domain/v1/ — use your Miniflux credentials
• Fever API: Enable per-user under Settings → Integrations → Fever. Set a separate Fever password.

Compatible apps: NetNewsWire, Reeder, FeedMe, ReadKit, Fluent Reader.

Full-Text Content Fetching

Miniflux can scrape full article content from feeds that only provide summaries. Enable per-feed:

1. Edit the feed settings
2. Check Fetch original content

Miniflux uses a built-in readability parser — no extensions needed.

Advanced Configuration (Optional)

OAuth2/OIDC Authentication

Miniflux supports Google and OIDC authentication:

environment:
  OAUTH2_PROVIDER: "oidc"
  OAUTH2_CLIENT_ID: "your-client-id"
  OAUTH2_CLIENT_SECRET: "your-client-secret"
  OAUTH2_REDIRECT_URL: "https://rss.example.com/oauth2/oidc/callback"
  OAUTH2_OIDC_DISCOVERY_ENDPOINT: "https://auth.example.com/.well-known/openid-configuration"
  OAUTH2_USER_CREATION: "1"

Webhooks and Integrations

Miniflux has built-in integrations for:

• Pinboard, Instapaper, Wallabag, Linkding, Shaarli (save articles)
• Matrix, Apprise, Ntfy (notifications)
• Telegram bot (read articles in Telegram)

Configure under Settings → Integrations.

Reverse Proxy

Set BASE_URL to your public-facing domain:

environment:
  BASE_URL: "https://rss.example.com"

Nginx Proxy Manager config:

• Scheme: http
• Forward Hostname: miniflux
• Forward Port: 8080

See Reverse Proxy Setup for full configuration.

Backup

Back up the PostgreSQL database:

docker compose exec miniflux_db pg_dump -U miniflux miniflux > miniflux-backup-$(date +%Y%m%d).sql

Restore:

cat miniflux-backup.sql | docker compose exec -T miniflux_db psql -U miniflux miniflux

See Backup Strategy for a complete backup approach.

Troubleshooting

”relation does not exist” Error on Startup

Symptom: Miniflux fails to start with PostgreSQL errors about missing tables. Fix: Ensure RUN_MIGRATIONS=1 is set. If the database was partially created, drop and recreate it:

docker compose exec miniflux_db psql -U miniflux -c "DROP DATABASE miniflux;"
docker compose exec miniflux_db psql -U miniflux -c "CREATE DATABASE miniflux;"
docker compose restart miniflux

Feeds Stuck on “Waiting”

Symptom: Feeds never refresh, stuck in “Waiting for initial fetch” state. Fix: Check the Miniflux logs for network errors. Common causes: DNS resolution failure inside the container, or outbound connections blocked by a firewall.

docker compose logs miniflux | grep -i error

High CPU During Feed Refresh

Symptom: CPU spikes every polling cycle. Fix: Reduce BATCH_SIZE (default 100) and increase POLLING_FREQUENCY. If you have hundreds of feeds, BATCH_SIZE=50 and POLLING_FREQUENCY=120 is more reasonable.

Fever API Returns Empty Response

Symptom: Fever-compatible apps show no feeds or articles. Fix: Make sure Fever is enabled under Settings → Integrations → Fever and you’ve set a Fever-specific password. The Fever API endpoint is /fever/.

Resource Requirements

• RAM: ~30 MB idle, ~80 MB during feed refresh
• CPU: Very low — Go binary is extremely efficient
• Disk: ~50 MB for the application, PostgreSQL storage grows with article count

Verdict

Miniflux is the best RSS reader if you value simplicity and speed above all else. It’s faster than FreshRSS, uses less memory, and the UI is ruthlessly minimal — no clutter, no distractions, just your feeds. The trade-off: no extensions, no themes, and fewer customization options. If you want a full-featured reader with bells and whistles, use FreshRSS. If you want the fastest, cleanest reading experience, Miniflux is the one.

Frequently Asked Questions

How is Miniflux different from FreshRSS?

Miniflux is opinionated and minimal — one theme, no extensions, no plugins, no customization beyond environment variables. It is faster and uses less memory (~30 MB idle vs ~100 MB for FreshRSS). FreshRSS offers multiple themes, an extension system, XPath content scraping, and more configuration options. Choose Miniflux if you want speed and simplicity. Choose FreshRSS if you want customization and features.

Which mobile apps work with Miniflux?

Miniflux supports the Google Reader API and the Fever API, which are compatible with most RSS reader apps. Popular choices: NetNewsWire (iOS/macOS), Reeder (iOS/macOS), FeedMe (Android), ReadKit (macOS), and Fluent Reader (cross-platform). Configure the API endpoint in your app’s settings — Google Reader API uses /v1/, Fever uses /fever/.

Can Miniflux fetch full article content?

Yes. Miniflux includes a built-in readability parser that can scrape full article content from feeds that only provide summaries. Enable it per-feed by editing the feed settings and checking Fetch original content. No browser extensions or external services are required.

How much storage does Miniflux use?

The application itself uses ~50 MB. PostgreSQL storage grows with your article count and retention settings. With default settings (180 days unread retention), a moderate feed list (100-200 feeds) typically consumes 200-500 MB of database storage. Adjust CLEANUP_ARCHIVE_UNREAD_DAYS and CLEANUP_ARCHIVE_READ_DAYS to control growth.

Does Miniflux support OPML import?

Yes. Import your feeds from any RSS reader by going to Feeds → Import and uploading an OPML file. Miniflux also supports OPML export for moving to another reader. All major RSS readers support OPML, making migration straightforward.

Can I run Miniflux without Docker?

Yes. Miniflux is a single Go binary with no dependencies other than PostgreSQL. You can download it from the GitHub releases page and run it directly. However, Docker Compose is the easiest way to manage both Miniflux and PostgreSQL together.

Related

• Miniflux: Feed Import Not Working — Fix
• Miniflux vs Tiny Tiny RSS: RSS Readers Compared
• Best Self-Hosted RSS Readers
• FreshRSS vs Miniflux
• How to Self-Host FreshRSS
• Replace Feedly with Self-Hosted RSS
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy