bfren/freshrss repository overview

⁠FreshRSS

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

FreshRSS⁠ - a self-hosted RSS and Atom feed reader - installed and set up automatically.

It is Nginx + PHP⁠ (PHP 8.5) with:

• FreshRSS 1.30.1 installed, read-only, outside your volume - so upgrading means pulling a new image
• the PHP extensions FreshRSS requires, including SQLite, MySQL and PostgreSQL drivers
• automatic installation on first start, using environment variables - no set-up wizard
• feeds refreshed every 15 minutes

It is designed to run behind a reverse proxy that handles SSL, such as Caddy Proxy⁠.

⁠Quickstart

With a MariaDB database (e.g. bfren/mariadb⁠):

services:
  freshrss:
    image: quay.io/bfren/freshrss:5.2
    environment:
      - BF_FR_BASE_URL=https://rss.example.com
      - BF_FR_USER_NAME=ben
      - BF_FR_USER_PASS=change-me
      - BF_FR_DB_HOST=db
      - BF_FR_DB_USER=freshrss
      - BF_FR_DB_PASS=change-me-too
    ports:
      - "8080:80"
    volumes:
      - ./v/data:/data

Or, without a database server, set BF_FR_DB_TYPE=sqlite (the database is then kept in /data).

On first start FreshRSS is installed and your user created. Open the site and log in.

⁠Features

• 📰 FreshRSS, ready to use on first start
• 🗄️ MySQL / MariaDB (default), PostgreSQL or SQLite
• ⏱️ Feeds refreshed every 15 minutes by cron
• 🔒 FreshRSS's own updater turned off - updates come with the image
• 🗜️ Everything from Nginx + PHP⁠: PHP-FPM, OPcache, compression, logs and a health check

⁠Tags

Images are published to Docker Hub (bfren/freshrss) and Quay.io (quay.io/bfren/freshrss) for linux/amd64, linux/arm/v7 and linux/arm64. There is one build, on PHP 8.5.

⁠Configuration

⁠Ports

⁠Volumes

⁠Environment Variables

These are used only on first start, to install FreshRSS. After that, change settings in FreshRSS itself.

Nginx + PHP⁠ adds the PHP settings, and Nginx⁠ the nginx ones.

⁠How It Works

⁠Starting

When the container starts, Nginx + PHP⁠ sets up nginx and PHP, then this image:

1. serves FreshRSS's p (public) folder instead of /www/public, and links FreshRSS's data folder to /data
2. if /data/config.php exists, treats FreshRSS as installed and does nothing more
3. otherwise installs it with FreshRSS's command-line tools: prepares the data folders, sets up the database, creates your user and fetches their feeds

If the installation fails, the container stops - check docker logs for the reason.

⁠Refreshing feeds

Every 15 minutes, cron runs fr-actualize, which runs FreshRSS's actualize_script.php to fetch new articles for every user. You can run it yourself:

docker exec <container> fr-actualize

⁠Testing

./test.nu        # builds the image and runs /test

/test runs this image's tests alongside the base images' tests, and fails if tests don't execute. They check how the first user's name and password are read (including the older BF_FR_USER / BF_FR_PASS names), that installation is recorded, that FreshRSS matches the version in the build log, the required PHP extensions are loaded, and nginx accepts the configuration.

⁠Troubleshooting

⁠The container stops on first start

The installation failed. The usual causes are a missing BF_FR_BASE_URL, BF_FR_USER_NAME or BF_FR_USER_PASS, or a database that can't be reached - check docker logs and fix the variables. If /data/config.php was created before it failed, empty /data (and the database) before starting again - otherwise FreshRSS will be treated as installed.

⁠I changed an environment variable but nothing happened

The variables are only used on first start. Change the setting in FreshRSS instead, or (to start completely afresh) empty /data and the database.

⁠FAQs

⁠Can I use SQLite instead of a database server?

Yes - set BF_FR_DB_TYPE=sqlite before the first start. The database is then kept in /data.

⁠How do I update FreshRSS?

Pull a newer tag and recreate the container. FreshRSS's own updater is turned off, because FreshRSS is read-only inside the image.

⁠Licence

⁠Copyright