Install Miniflux on a VPS with Docker and HTTPS

A personal RSS reader works well for software release notes, engineering blogs, project updates and industry news. Open the same account on a laptop or phone, mark articles as read and return to bookmarked items later.

The setup below gives Caddy the public HTTPS endpoint and keeps the application and database on the Compose network. After installation, you will create an administrator, import feeds and prepare a recoverable database backup.

What you can do with a self-hosted RSS reader

Miniflux supports OPML import and export, categories, bookmarks and full-text search. Its feed parser handles RSS, Atom and JSON Feed. The project publishes its supported formats and integrations in the feature list. Explore Miniflux features.

Start with a small selection of sources. A reader becomes easier to use when each category serves a purpose, such as security announcements, programming or company updates.

1. Prepare a VPS, hostname and Docker

You need a Linux VPS with SSH access, Docker Engine, the Compose plugin and a hostname such as rss.example.com. The examples use Bash and OpenSSL. Our Docker installation guide covers an Ubuntu base. Install Docker on Ubuntu.

• Point the hostname's A record to the VPS. Add an AAAA record when IPv6 reaches the same server correctly.
• Allow inbound TCP 80 and 443 for the Caddy configuration. UDP 443 supports HTTP/3. Keep your SSH connection available.
• Confirm that the host has memory and disk capacity for PostgreSQL, feed history and its existing workloads.
• Use an existing reverse proxy or reserve ports 80 and 443 for this stack. Check port ownership before starting another proxy.

HYEHOST Cloud VPS includes root access in Wolverhampton, Ashburn and Auckland. Choose the region around the devices that will use the reader, then monitor resource use as the feed list grows. Compare Cloud VPS plans.

Create a new project directory and confirm Compose is installed.

mkdir -p ~/miniflux
cd ~/miniflux
docker compose version

2. Create the database credential

In the new project directory, generate a hexadecimal password and save it in .env. Run this initialisation once, then retain the file for future starts and updates.

umask 077
printf 'MINIFLUX_DB_PASSWORD=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .env

The password is used in both PostgreSQL's initial configuration and Miniflux's connection URL. Hexadecimal output fits safely in that URL. Protect .env and its backup copies, and coordinate any later password rotation with the database account. The project documents its database connection parameters. Read the database configuration guide.

3. Add the Docker Compose services

Save the following as compose.yaml. Replace rss.example.com with your real hostname.

services:
  db:
    image: postgres:18.6
    restart: unless-stopped
    environment:
      POSTGRES_DB: miniflux
      POSTGRES_USER: miniflux
      POSTGRES_PASSWORD: ${MINIFLUX_DB_PASSWORD:?Set MINIFLUX_DB_PASSWORD in .env}
    volumes:
      - miniflux_db:/var/lib/postgresql
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "miniflux", "-d", "miniflux"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s

  miniflux:
    image: miniflux/miniflux:2.3.5
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://miniflux:${MINIFLUX_DB_PASSWORD:?Set MINIFLUX_DB_PASSWORD in .env}@db:5432/miniflux?sslmode=disable
      RUN_MIGRATIONS: "1"
      BASE_URL: https://rss.example.com
      HTTPS: "1"
      LISTEN_ADDR: 0.0.0.0:8080
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "/usr/bin/miniflux", "-healthcheck", "http://127.0.0.1:8080/healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      miniflux:
        condition: service_healthy

volumes:
  miniflux_db:
  caddy_data:
  caddy_config:

The Miniflux and PostgreSQL images are pinned to the versions checked for this guide. Caddy follows its 2.x Alpine tag. Record the tested image versions when you maintain the deployment, and review release notes before changing them.

PostgreSQL 18 uses the parent volume mount at /var/lib/postgresql. The database health check controls application startup, and the application health check controls Caddy startup. Docker explains how these readiness conditions work. Read about Compose startup order.

Caddy reaches miniflux:8080 through the project network. Database traffic stays inside that network, where the example uses sslmode=disable. A deployment with a database on another server needs connection and TLS settings appropriate to that route. The official Miniflux Docker guide provides the underlying service configuration. Read the Docker installation guide.

RUN_MIGRATIONS prepares the database schema. BASE_URL sets the external URL, and HTTPS enables secure cookies and HSTS. Caddy handles the browser-facing TLS connection while Miniflux listens on HTTP inside the network. Review the configuration options.

4. Configure HTTPS with Caddy

Save this as Caddyfile, using the same hostname as BASE_URL.

rss.example.com {
    reverse_proxy miniflux:8080
}

Caddy obtains and renews a public certificate when the hostname resolves correctly, the required ports are reachable and its certificate data is persistent. The Compose volumes retain that state when containers are replaced. Read Caddy's HTTPS requirements.

Validate the Compose configuration, start the stack and inspect service status.

docker compose config --quiet
docker compose up -d --wait
docker compose ps
docker compose logs --tail=80 db miniflux caddy

Check the public HTTPS certificate in your browser. If startup fails, use the failing service's logs to identify whether the problem is database readiness, an application migration, DNS or certificate issuance.

5. Create your administrator account

After Miniflux passes its health check, run the administrator command. It prompts for the username and password interactively.

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

Sign in at https://rss.example.com using the account you created. Store the password in your password manager and create separate user accounts when other people use the server. The CLI also provides an interactive password-reset command. Read the Miniflux CLI reference.

docker compose exec miniflux /usr/bin/miniflux -reset-password

Version 2.3.5 groups password, passkey and linked-account settings on the Authentication page under Settings. Keep account recovery information available before changing the sign-in method. Review the authentication changes.

6. Add feeds and import your OPML subscriptions

Add a subscription through the feed interface, enter a website or feed URL and select the discovered feed. For a first test, add the HYEHOST blog feed.

https://hyehost.org/blog/feed.xml

Import an OPML file when moving from another reader. Review the resulting categories, open a few articles and mark one as read. Then sign in from a second device and confirm that the same reading state appears.

Export OPML periodically to retain a portable list of subscriptions. The PostgreSQL database holds the broader application state used by the backup procedure below.

Some feeds provide only an excerpt. Miniflux can fetch an article's original content, and per-feed scraper rules can help with specific layouts. Enable this selectively and check the result because it adds website requests and processing. Read about feed and article controls.

7. Set up mobile reading and optional integrations

The web interface adapts to mobile screens and can be added to a phone's home screen. If you prefer a dedicated reader, use an application listed in Miniflux's compatibility documentation and follow its required integration setup. Find compatible reader applications.

For automation or API clients, create a separate API key in Settings and label it for the application using it. Store the key in that application's credential settings and revoke it when the integration is retired. Miniflux documents per-application keys and the supported authentication methods. Read the API authentication reference.

You can also connect selected feed events to a notification workflow. Miniflux lists an ntfy integration, and our ntfy guide covers a self-hosted notification endpoint. Start with one selected feed to keep alerts manageable. Read the ntfy integration guide. Set up ntfy on a VPS.

8. Back up the database and configuration

Keep copies of compose.yaml, Caddyfile, .env and a PostgreSQL export. Account details, reading state and integration credentials make these sensitive recovery files. Encrypt the off-server copy and restrict access.

For a pre-update backup, choose a new archive filename, pause Miniflux and create a custom-format dump inside the database container.

mkdir -p backups
chmod 700 backups
docker compose stop miniflux

docker compose exec -T db pg_dump \
  --username=miniflux --dbname=miniflux \
  --format=custom --file=/tmp/miniflux-before-update.dump

docker compose cp \
  db:/tmp/miniflux-before-update.dump \
  ./backups/miniflux-before-update.dump

chmod 600 ./backups/miniflux-before-update.dump
docker compose start miniflux

Check each command's exit status and retain the archive only after the export and copy succeed. If an error interrupts the sequence, investigate it and bring the paused application back when appropriate. PostgreSQL documents the custom archive format and consistent exports. Read the pg_dump reference.

Test recovery on a separate VPS. Copy the configuration and archive into a new directory, set BASE_URL and the Caddy hostname to a dedicated test hostname, and point its DNS to that test server. The project name miniflux-restore-test below gives its database an independent named volume.

Start the test database first, copy the archive into its container and restore it into the empty miniflux database.

docker compose -p miniflux-restore-test up -d --wait db

docker compose -p miniflux-restore-test cp \
  ./backups/miniflux-before-update.dump \
  db:/tmp/miniflux-before-update.dump

docker compose -p miniflux-restore-test exec -T db pg_restore \
  --username=miniflux --dbname=miniflux \
  --exit-on-error --no-owner \
  /tmp/miniflux-before-update.dump

Run those recovery commands from the test project's directory. After restoration succeeds, start the full test stack with docker compose -p miniflux-restore-test up -d --wait. Check its accounts, subscriptions, bookmarks and reading state, and review restored integration settings before enabling notifications. Failed restores may leave partial objects, so prepare a fresh empty target for another attempt. Read the pg_restore reference.

HYEHOST Storage Box can hold an encrypted off-server copy of the archive and configuration. Our existing rclone guide covers an SFTP backup workflow. Explore Storage Box. Set up encrypted backup storage.

9. Maintain the reader

Read the target release notes, save the current image tags and configuration, then take and test a database backup before an update. Change the Miniflux tag deliberately and use the documented migration process. The project publishes an upgrade checklist. Read the Miniflux upgrade procedure.

Review retention as the database grows. The configuration includes separate cleanup ages for read and unread entries. Choose values around how long you want that history available and include the database size in your monitoring.

Monitor the public login page and the application's health endpoint from another system. A database or container restart can recover the process while a DNS or certificate problem still needs attention. Our monitoring guide includes an independent checker. Set up Uptime Kuma.

Common Miniflux setup problems

Miniflux VPS hosting FAQ