Deployment guide

Freshrss

Overview

FreshRSS is a fast, self-hosted RSS and Atom feed aggregator and reader. It pulls together the sites, blogs, newsletters and podcasts you follow into a single clean reading interface that you own and control, with no tracking and no third-party cloud.

The SecureAnyCloud image installs FreshRSS 1.29.1 served by nginx and PHP 8.3 FPM on a hardened Ubuntu 24.04 LTS base, patched at build time. FreshRSS runs behind an nginx reverse proxy on port 80 and stores everything in a self-contained SQLite database on a dedicated Azure data disk. It generates a unique administrator password on the first boot of every VM. Mobile and desktop reader apps connect over the built-in Google Reader and Fever compatible APIs.

What you get:

FreshRSS 1.29.1 served by nginx and PHP 8.3 FPM, managed by systemd
The FreshRSS web interface on :80 with a per-VM admin account
A self-contained SQLite database (no separate database server to run or tune)
A per-VM admin password generated on first boot and recorded in a root-only file
The Google Reader and Fever compatible APIs enabled for mobile and desktop reader apps
A dedicated Azure data disk at /var/lib/freshrss for the database, cache, favicons and feeds
nginx.service and php8.3-fpm.service as systemd units, enabled and active
An unauthenticated /healthz endpoint for Azure Load Balancer health probes
24/7 SecureAnyCloud support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet and subnet in the target region.
Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point. Size up for large feed collections or many users.
NSG inbound rules: allow 22/tcp from your management network and 80/tcp for the web interface.

FreshRSS serves plain HTTP on port 80. For production, terminate TLS in front of it with your own domain.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource and search the Marketplace for FreshRSS by SecureAnyCloud. Select Create.

On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTP (80).

Review the dedicated data disk on the Disks tab, then select Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:freshrss-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name freshrss \
  --image sac1647283583153:freshrss-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
az vm open-port --resource-group <your-rg> --name freshrss --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

nginx serves FreshRSS on port 80 and forwards PHP requests to PHP 8.3 FPM over a local socket. Confirm that both services are active and that nginx is listening on port 80:

systemctl is-active nginx php8.3-fpm freshrss-firstboot ss -tlnp | grep ':80 '

Step 5 - Retrieve your admin password

On the first boot of every VM, freshrss-firstboot.service generates a unique administrator password. It seeds the FreshRSS admin account with that password, sets the same password as the Google Reader and Fever API password, and writes the details to a root-only file. Read the file with:

sudo cat /root/freshrss-credentials.txt

Step 6 - Confirm the stack and health endpoint

nginx serves an unauthenticated /healthz endpoint for load balancer probes. Confirm the FreshRSS release and the PHP version, check that the web interface responds, and check that the Fever API is enabled:

grep -oP "FRESHRSS_VERSION = '\K[^']+" /var/www/freshrss/constants.php php -v | head -1 curl -sI http://127.0.0.1/healthz | head -1 curl -s "http://127.0.0.1/api/fever.php?api"

Step 7 - Open FreshRSS in your browser

Browse to http://<vm-public-ip>/. FreshRSS redirects anonymous visitors to the sign-in page.

Step 8 - Sign in and read your feeds

Enter admin and the password from Step 5, then select Sign in. FreshRSS opens the reader. Your subscriptions are listed in the left-hand sidebar, and articles appear in the main pane. The image ships with a small set of default subscriptions, so you have content to read straight away.

Step 9 - Subscribe to a feed

Select the + (subscribe) control at the top of the sidebar and paste a site or feed URL. FreshRSS discovers the feed and adds it. You can organize feeds into categories, and you can import an existing collection from another reader as an OPML file from Settings then Import / export.

Step 10 - Configure FreshRSS and connect mobile apps

Open Settings (the cog icon) to control refresh frequency, reading behavior, themes, sharing and user accounts. FreshRSS refreshes feeds automatically. You can also add extra user accounts for a shared household or team instance.

To read on the go, point a compatible mobile or desktop app (for example Reeder, Fluent Reader, FeedMe or NetNewsWire) at this instance. Under Settings then Profile, enable the API and confirm the API password. In your app, choose the Google Reader API or Fever API and use these endpoints with the admin username and the API password from Step 5:

Google Reader API: http://<vm-public-ip>/api/greader.php Fever API: http://<vm-public-ip>/api/fever.php

Step 11 - Confirm your data lives on the dedicated disk

All FreshRSS data lives under /var/lib/freshrss, a dedicated Azure data disk that is captured into the image and re-provisioned on every VM. It holds the SQLite database, the per-user configuration, the feed cache and favicons:

df -h /var/lib/freshrss | tail -1 ls /var/lib/freshrss findmnt -no SOURCE,TARGET,FSTYPE /var/lib/freshrss

Maintenance

Back up your data. A backup is a copy of /var/lib/freshrss (the SQLite database, per-user config, cache and favicons). Snapshot the data disk or tar the directory. FreshRSS also ships ./cli/db-backup.php for database-only exports.
Add users. Sign in as admin and use the user management screen under Settings, or run sudo -u www-data php /var/www/freshrss/cli/create-user.php --user <name> --password <pw> on the VM.
Refresh feeds. FreshRSS refreshes feeds on a schedule. Force a refresh for a user with sudo -u www-data php /var/www/freshrss/cli/actualize-user.php --user admin.
Mobile and desktop apps. Connect over the Google Reader or Fever API endpoints shown in Step 10 with the admin user and the API password.
Security updates. Unattended security upgrades are enabled, so the OS keeps itself patched. Reboot when a new kernel is installed.
TLS. For production, front FreshRSS with your own domain and a TLS-terminating reverse proxy or Azure Application Gateway.

Support

SecureAnyCloud provides 24/7/365 expert technical support for this image. Contact sales@secureanycloud.com.

FreshRSS is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This image is provided by SecureAnyCloud, and additional charges apply for build, maintenance and 24/7 support.

Deploy on Azure

Launch FreshRSS on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Overview

FreshRSS is an open-source, self-hosted RSS and Atom feed aggregator and reader. It lets you follow news sites, blogs, podcasts, YouTube channels and any other source that publishes a feed, and read everything in one fast, clean web interface that you own and control.

This image runs FreshRSS as a PHP application. nginx answers on port 80 (and 443 once you add TLS) and passes requests to php-fpm over a local socket. FreshRSS uses a self-contained SQLite database, so there is no separate database server to install, tune or back up.

What you get:

FreshRSS served by nginx and php-fpm, with systemd-managed services
A dedicated EBS data volume mounted at /var/lib/freshrss, independently resizable and separate from the operating system disk. It holds the configuration, the SQLite feed database, the article and favicon cache, PubSubHubbub state and extension data.
Program code at /var/www/freshrss, with only the public /var/www/freshrss/p directory exposed to the web
A one-shot first-boot service that generates a single administrator account with a per-instance password and writes the login to /root/freshrss-credentials.txt with mode 0600
No shared or default credentials in the image

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 that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your readers use.
The AWS CLI (version 2) installed locally, if you plan to deploy from the command line.

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 FreshRSS. Select the SecureAnyCloud listing, choose Select, then choose Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet, then 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 readers use. Leave the root volume at the default size or larger. The image adds a separate data volume for the reader content automatically.

Select Launch instance. First-boot initialization takes only a few seconds after the instance state becomes Running and the status checks pass.

Launch the instance from the AWS CLI

The following command launches an instance from the SecureAnyCloud FreshRSS 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.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=freshrss-01}]'

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

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 AMI variant you launched. For FreshRSS on Ubuntu 24.04, the login user is ubuntu.

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

The per-instance administrator password is written to a root-only file on first boot. Read it with:

sudo cat /root/freshrss-credentials.txt

The file contains the reader URL, the admin username (admin) and the generated FRESHRSS_ADMIN_PASSWORD. These credentials are unique to this instance.

Confirm that the services are running and that the reader answers locally:

systemctl is-active nginx php8.3-fpm curl -s -o /dev/null -w 'healthz %{http_code}\n' http://127.0.0.1/healthz curl -s -o /dev/null -w 'login %{http_code}\n' 'http://127.0.0.1/i/?c=auth&a=login'

nginx and php8.3-fpm report active, and both HTTP checks return 200. The /healthz endpoint is unauthenticated, so you can use it for a load balancer or uptime monitor.

First sign-in

Open the reader in your browser at http://<instance-public-ip>/. The FreshRSS login page loads immediately. There is no installer and no database setup.

Enter the username admin and the password from /root/freshrss-credentials.txt, then select Login. FreshRSS never sends your plaintext password over the wire. The login form hashes it in your browser and submits only a one-time challenge, so make sure JavaScript is enabled.

Subscribe to feeds

After you sign in, you land on the reading stream. A fresh instance starts empty, so add some feeds first. Select Subscription management at the top left, then select Add a feed or category. Paste the address of any RSS or Atom feed, for example a news site, a blog, a subreddit, a YouTube channel or a podcast.

FreshRSS discovers the feed, fetches recent articles and adds the feed to your chosen category.

If you already use another reader, choose Import / export and upload your existing OPML file to bring all of your subscriptions across at once. You can export your subscriptions the same way at any time.

Read your feeds

On the main stream, new articles appear grouped by category, with an unread count next to each feed and category. Open an article to read it inline, mark items as read as you scroll, star the ones you want to keep, and use the search box to find articles across every feed.

Keyboard shortcuts, several reading layouts and light and dark themes are available. Per-feed refresh and retention rules let you tune how much history each feed keeps.

Configuration, users and the mobile APIs

Select the gear icon at the top right to open the configuration area. There you can set your display, reading, archiving and sharing preferences and manage extensions. Under the administration section, you can manage users, tune the system configuration and review the logs.

FreshRSS exposes Google Reader and Fever compatible APIs, so you can read and sync your feeds from popular mobile and desktop reader apps. Under Profile, set an API password for your account. Under System configuration, enable the API. Point your reader app at http://<instance-public-ip>/api/greader.php (Google Reader API) or http://<instance-public-ip>/api/fever.php (Fever API) with the username admin and the API password you set.

Configure HTTPS

The image serves plain HTTP on port 80, so it works the moment it boots. For production, put the reader behind TLS. The simplest approach is to place the instance behind an Application Load Balancer or Amazon CloudFront with an AWS Certificate Manager certificate. Terminate TLS there and forward to port 80 on the instance.

Alternatively, terminate TLS on the instance itself with a certificate from your certificate authority. Point a DNS record at the instance, obtain a certificate for that name, and add a TLS server block to the nginx site at /etc/nginx/sites-available/sac-freshrss that listens on port 443 with your certificate, and keep the existing PHP and routing rules. Open port 443 in the security group. When FreshRSS is reached over HTTPS, it automatically uses secure cookies.

Backup and maintenance

All of the reader's state lives under /var/lib/freshrss on the dedicated EBS data volume, so your backup strategy is to snapshot that volume. Create an Amazon EBS snapshot of the data volume on a schedule with Amazon Data Lifecycle Manager, or copy the directory to Amazon S3.

FreshRSS also ships command-line tools under /var/www/freshrss/cli, which you run as the www-data user. For example, use sudo -u www-data php /var/www/freshrss/cli/list-users.php to list accounts, import-for-user.php and export-opml-for-user.php for OPML, and db-backup.php to back up the database. Feeds refresh automatically. To force a refresh, run sudo -u www-data php /var/www/freshrss/cli/actualize-user.php --user admin.

Keep the operating system patched with sudo apt-get update && sudo apt-get upgrade. The nginx and php8.3-fpm services are managed by systemd and start automatically on boot.

Support

This image is published and supported by SecureAnyCloud. If you need help deploying or operating it, contact SecureAnyCloud support by email or chat. We can help with deployment, feed and category organization, OPML import and export, API and mobile-app setup, extension selection, storage and retention tuning, and backup and upgrade planning.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Deploy on AWS

Launch FreshRSS on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS