Miniflux on AWS User Guide

Overview

This image runs Miniflux, the open source minimalist and fast self-hosted RSS/Atom/JSON feed reader - a privacy-respecting alternative to hosted readers, with a clean reader interface, keyboard shortcuts, full-text fetching, integrations and a REST API (plus the Google Reader and Fever APIs for mobile apps).

The Miniflux server runs behind nginx as a reverse proxy. PostgreSQL is the datastore for feeds, entries and settings; the server is otherwise stateless. The server listens on 127.0.0.1:8080 and is reached through nginx on port 80 (and 443 once you add TLS); the database binds to the loopback interface only.

An administrator account and the PostgreSQL password are generated on the first boot of every deployed instance; the login is written to /root/miniflux-credentials.txt with mode 0600.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users will reach the reader on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line
• Outbound internet access from the instance so Miniflux can fetch feeds

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Miniflux. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.medium or larger - Miniflux is lightweight. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes under a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Miniflux Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.medium \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=miniflux-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Administrator Login

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/miniflux-credentials.txt

You will see a plain text file containing the Miniflux URL, the administrator username (admin) and the password. From the same SSH session you can confirm the deployment is healthy - the health endpoint is open:

curl -fsS http://127.0.0.1/healthcheck

OK

An OK response confirms the full stack - nginx, the Miniflux server and PostgreSQL - is serving.

Step 4: First Sign-in

Open a web browser and navigate to http://<public-ip>/. Miniflux presents its sign-in page. Enter the username admin and the password from /root/miniflux-credentials.txt, then select Login.

The Miniflux sign-in, served on first boot with a per-instance administrator login.

Step 5: Add Feeds and Read

Select Feeds, then Add feed, paste a site or feed URL, and Miniflux discovers and subscribes to it. Your unread entries appear in a clean, fast list with keyboard shortcuts; star items, fetch the original article inline, and open the source.

The Miniflux reader - a clean, fast unread list with mark-as-read, star and full-text actions.

To migrate from another reader, use Import to upload an OPML file of your existing subscriptions.

Step 6: Settings, Integrations and Mobile Apps

Open Settings to set reader preferences, manage Integrations (third-party services), generate API Keys for the REST API, manage Sessions, and add Users. Miniflux also exposes the Google Reader and Fever APIs, so you can connect popular mobile and desktop RSS clients to your instance.

Miniflux settings - reader preferences, integrations, API keys, sessions and multi-user.

Step 7: Enable HTTPS with Let's Encrypt

For any production deployment serve Miniflux over HTTPS so logins cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following assumes you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d reader.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

After certbot finishes, set the base URL so generated links are correct, then restart with sudo sed -i 's|^BASE_URL=.*|BASE_URL=https://<your-domain>/|' /etc/miniflux.conf && sudo systemctl restart miniflux.

Step 8: Backups and Maintenance

Miniflux keeps all of its state - feeds, entries, users and settings - in PostgreSQL. Back it up regularly:

sudo -u postgres pg_dump miniflux > <backup-dir>/miniflux-db-$(date +%F).sql

Ship the dump to an Amazon S3 bucket or another object store. Because the database is on its own EBS volume, you can also take coordinated EBS snapshots. Feeds are refreshed on a schedule by the Miniflux scheduler; you can trigger a refresh from the UI at any time. For kernel and package updates, Ubuntu's unattended-upgrades is enabled by default. To upgrade Miniflux, replace /usr/local/bin/miniflux with a newer release and restart - migrations run automatically. See https://miniflux.app/docs/.

Step 9: Scaling and Operations

• Move PostgreSQL to Amazon RDS for PostgreSQL and update DATABASE_URL in /etc/miniflux.conf
• Put the web tier behind an Application Load Balancer if you need high availability
• Use the REST API or Google Reader/Fever APIs to integrate Miniflux with other tools and mobile apps

Each of these is documented in the official Miniflux documentation at https://miniflux.app/docs/.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general Miniflux questions consult the documentation at https://miniflux.app/docs/. Miniflux is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement.