This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
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.
Originally published with full interactive benchmark metrics and server sizing notes at https://vpsfolio.pages.dev/self-host-miniflux-docker/.
