VPSFolio

2026-11-20 · miniflux · rss · docker · self-hosting

Self-Host Miniflux with Docker: Minimalist RSS Reader

Run Miniflux, a fast Go RSS reader, with PostgreSQL in Docker Compose. Covers env vars, reverse proxy, backups, and updates.

Bench run · 2026-11-20 Verified
miniflux/v2
Total RAM
43.8 MB
Startup
76.4 s
Port
8080
HTTP
200
Per container db 28.8 MB · miniflux 15.0 MB
postgres:16-alpine · 2 containers · miniflux/v2

What Miniflux does and what it needs

Miniflux is a minimalist feed reader written in Go. It fetches Atom, RSS, and JSON feeds, strips trackers, sanitizes HTML, and gives you a distraction-free reading UI with keyboard shortcuts and full-text search. It talks only to PostgreSQL — no Redis, no ORM, no message broker.

The official image is published on Docker Hub, GitHub Registry, and Quay.io with ARM and RISC-V builds. The binary is statically compiled and bundles all static assets, so the container is tiny. The upstream project does not publish a minimum RAM figure; the README notes it uses only a couple of MB of memory and negligible CPU even with hundreds of feeds. Idle footprint is small; memory grows with concurrent feed refreshes, full-text search index size, and the number of stored articles.

Miniflux can terminate TLS itself with Let’s Encrypt, but in a container stack you want a reverse proxy in front. This guide runs Miniflux behind Caddy or Nginx on the same VPS and binds the app to localhost only.

Prerequisites, ports, and volume constraints

  • A Linux VPS with Docker Engine 24+ and the Compose plugin (docker compose version).
  • A domain pointing at the VPS if you want HTTPS. You can test over an SSH tunnel without one.
  • Port 8080 is Miniflux’s default HTTP port inside the container. We bind it to 127.0.0.1:8080 so it is not exposed unencrypted on the public IP.
  • PostgreSQL 13+ is required. The Compose file below uses postgres:16-alpine.
  • Two named volumes: miniflux-db for PostgreSQL data and miniflux-data for Miniflux’s local storage (favicons, media cache).

Miniflux reads its configuration from environment variables. The important ones for a production deployment are DATABASE_URL, RUN_MIGRATIONS, BASE_URL, LISTEN_ADDR, and TZ. BASE_URL must match the public URL exactly, including scheme, or generated links and the media proxy will break.

Production Docker Compose setup

Create a project directory and generate secrets first:

mkdir -p ~/miniflux && cd ~/miniflux
openssl rand -hex 32   # use as POSTGRES_PASSWORD

Write the Compose file:

cat <<'EOF' > compose.yml
services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: miniflux
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: miniflux
      TZ: ${TZ:-UTC}
    volumes:
      - miniflux-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U miniflux -d miniflux"]
      interval: 10s
      timeout: 5s
      retries: 10

  miniflux:
    image: miniflux/miniflux:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      DATABASE_URL: postgres://miniflux:${POSTGRES_PASSWORD}@db:5432/miniflux?sslmode=disable
      RUN_MIGRATIONS: "1"
      BASE_URL: ${BASE_URL:-http://localhost:8080}
      LISTEN_ADDR: 0.0.0.0:8080
      TZ: ${TZ:-UTC}
    volumes:
      - miniflux-data:/var/lib/miniflux

volumes:
  miniflux-db:
  miniflux-data:
EOF

Write the .env file. Replace POSTGRES_PASSWORD with the output of openssl rand -hex 32, and set BASE_URL to your real public URL:

cat <<'EOF' > .env
POSTGRES_PASSWORD=replace-with-openssl-rand-hex-32
BASE_URL=https://reader.example.com
TZ=UTC
EOF
chmod 600 .env

Start the stack:

docker compose up -d
docker compose logs -f miniflux

On first boot Miniflux runs migrations and creates the schema. Create the admin user from the CLI:

docker compose exec miniflux /usr/bin/miniflux -create-admin

It prompts for username and password. Do this immediately — the login page is reachable as soon as the container is up.

Reverse proxy, HTTPS, and first-run hardening

Miniflux serves plain HTTP on 8080 and relies on the proxy for TLS. Two things matter for the proxy config:

  1. BASE_URL must match the public URL. If you set BASE_URL=https://reader.example.com, the proxy must forward Host and X-Forwarded-Proto: https so Miniflux generates correct absolute links and the media proxy works.
  2. Upload and body size. Miniflux accepts OPML imports and article content; set a reasonable client_max_body_size (Nginx) or rely on Caddy’s defaults, which are generous.

Caddy example (/etc/caddy/Caddyfile):

reader.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8080 {
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-Host {host}
    }
}

Nginx example:

server {
    listen 443 ssl http2;
    server_name reader.example.com;
    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Miniflux does not use WebSockets for its UI, so no upgrade headers are required. If you use the REST API or Fever/Google Reader compatibility endpoints from mobile clients, they go through the same proxy.

First-run hardening:

  • Create the admin user immediately after docker compose up -d and before exposing the proxy.
  • In Settings → Users, disable public registration if you do not need it. Miniflux does not enable self-registration by default, but verify.
  • Enable passkeys (WebAuthn) in the user profile if your browser supports it; it is stronger than a password alone.
  • If you test without a domain, keep the 127.0.0.1:8080 binding and use ssh -L 8080:127.0.0.1:8080 user@vps to reach it locally. Do not change the binding to 0.0.0.0 on a public VPS.

Updating, backups, and common pitfalls

Update:

cd ~/miniflux
docker compose pull
docker compose up -d
docker compose logs --tail=50 miniflux

Migrations run automatically because RUN_MIGRATIONS=1. Check the logs for migration errors before walking away.

Backup the database:

docker compose exec -T db pg_dump -U miniflux miniflux | gzip > miniflux-$(date +%F).sql.gz

Backup the data volume (favicons, media cache — not strictly required, but useful for a fast restore):

docker run --rm -v miniflux_miniflux-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/miniflux-data-$(date +%F).tar.gz -C /data .

Adjust the volume prefix (miniflux_) to match your Compose project name. Restore by piping the SQL dump back into psql inside the db container.

Pitfalls from the docs:

  • BASE_URL mismatch. If BASE_URL says http:// but users hit https://, the media proxy and share links break, and some integrations reject the callback. Change BASE_URL in .env and restart the container — no rebuild needed.
  • Feed refresh and cron. Miniflux has an internal scheduler, but if you run it behind a proxy that strips long-lived connections or you scale to multiple replicas, use the documented cron mode instead of the internal scheduler. Running two schedulers against one database causes duplicate fetches.
  • PostgreSQL version. Miniflux requires PostgreSQL 13 or newer. Pinning postgres:16-alpine is safe; do not downgrade the volume after an upgrade without a dump.
  • Tracker stripping and media proxy. The media proxy needs BASE_URL to be reachable from the browser. If you put Miniflux behind an auth proxy that blocks /proxy/, images in articles will fail to load.

Measured in our sandbox run: total memory 43.8 MB (sum of per-container peaks over a 30s idle window after startup) across 2 containers; largest container 28.8 MB; published port(s) 8080; HTTP probe returned 200. The run took 76.4s including the image download. Required secret(s) POSTGRES_PASSWORD were generated for the test run, as the tutorial instructs. Container breakdown: db 28.8 MB, miniflux 15.0 MB.


Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.