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.
- Total RAM
- 43.8 MB
- Startup
- 76.4 s
- Port
- 8080
- HTTP
- 200
db 28.8 MB
· miniflux 15.0 MB
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
8080is Miniflux’s default HTTP port inside the container. We bind it to127.0.0.1:8080so 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-dbfor PostgreSQL data andminiflux-datafor 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:
BASE_URLmust match the public URL. If you setBASE_URL=https://reader.example.com, the proxy must forwardHostandX-Forwarded-Proto: httpsso Miniflux generates correct absolute links and the media proxy works.- 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 -dand 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:8080binding and usessh -L 8080:127.0.0.1:8080 user@vpsto reach it locally. Do not change the binding to0.0.0.0on 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_URLmismatch. IfBASE_URLsayshttp://but users hithttps://, the media proxy and share links break, and some integrations reject the callback. ChangeBASE_URLin.envand 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-alpineis safe; do not downgrade the volume after an upgrade without a dump. - Tracker stripping and media proxy. The media proxy needs
BASE_URLto 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.