Setting up FreshRSS on

Configuration

After installing all components, they must be configured correctly for FreshRSS to work.

1. Caddy Configuration

Caddy uses the Caddyfile for its configuration. We will configure it to serve FreshRSS and automatically obtain SSL certificates.

# Открытие файла Caddyfile для редактирования
sudo nano /etc/caddy/Caddyfile

Remove all existing content and insert the following, replacing yourdomain.com with your actual domain name:

yourdomain.com {
    # FreshRSS root directory
    root  /var/www/freshrss/p/

    # Enable gzip compression
    encode gzip

    # Strict-Transport-Security header for HTTPS
    header {
        Strict-Transport-Security max-age=31536000;
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        X-XSS-Protection "1; mode=block"
    }

    # Process PHP files via PHP-FPM
    php_fastcgi unix//run/php/php8.3-fpm.sock {
        # Additional options, if needed
    }

    # Protect data directory from direct access
    @data {
        path /data/
    }
    respond @data 403

    # Protect app directory from direct access
    @app {
        path /app/
    }
    respond @app 403

    # Protect config directory from direct access
    @config {
        path /config/
    }
    respond @config 403

    # URL rewrite for FreshRSS (frontend controller)
    try_files {path} {path}/ /index.php?{query}

    # Logging
    log {
        output file /var/log/caddy/freshrss_access.log
        format json
    }

    # Automatic SSL/TLS certificate acquisition
    tls {
        # You can specify an email for Let's Encrypt notifications
        # email [email protected]
    }
}

# Проверка конфигурации Caddy
sudo caddy validate --config /etc/caddy/Caddyfile

# Перезапуск Caddy
sudo systemctl reload caddy

# Открытие таблицы Cron для редактирования
sudo crontab -u www-data -e

# Update FreshRSS feeds every 15 minutes
/15     php /var/www/freshrss/app/actualize_script.php > /dev/null 2>&1

This command will run the FreshRSS update script every 15 minutes as the www-data user (under which PHP-FPM runs). Redirecting output to /dev/null prevents logs from being filled with unnecessary messages.

4. Verifying Functionality

To ensure everything is working correctly:

• Open https://yourdomain.com in your browser and ensure you see the FreshRSS interface.
• Try adding a few RSS feeds and verify that they update successfully.
• Check Caddy logs for errors:

sudo journalctl -u caddy --since "5 minutes ago"

• Check PHP-FPM logs:

sudo journalctl -u php8.3-fpm --since "5 minutes ago"

• Ensure that the cron job is running by checking the last feed update time in the FreshRSS admin panel.

At this point, your FreshRSS is fully configured and functional.

Backups and Maintenance

Regular backups and timely server maintenance are critically important aspects for any system. FreshRSS stores all your feeds, settings, and user data in the database and file system, so it's crucial to ensure their preservation.

1. What to Back Up

For FreshRSS, three main components need to be backed up:

1. MariaDB Database: Contains all your subscriptions, articles, read/unread statuses, users, and their settings. This is the most important component.
2. FreshRSS Data Directory: /var/www/freshrss/data/. This directory contains FreshRSS configuration files, cache, user settings, and other service data not stored in the DB.
3. Web Server Configuration Files: /etc/caddy/Caddyfile. Saving the Caddy configuration will allow for quick web server recovery if needed.

2. Simple Auto-Backup Script

Let's create a simple bash script that will perform backups. We will use mysqldump for the database and tar for file archives.

# Creating a directory for backups
sudo mkdir -p /opt/backups/freshrss
sudo chown freshrssuser:freshrssuser /opt/backups/freshrss

# Creating the backup script
nano /opt/backups/freshrss/backup_freshrss.sh

Insert the following content, replacing ВАШ_ПАРОЛЬ_БД with the FreshRSS database user password:

#!/bin/bash

# Variables
BACKUP_DIR="/opt/backups/freshrss"
DATE=$(date +%Y%m%d%H%M%S)
DB_NAME="freshrss_db"
DB_USER="freshrss_user"
DB_PASS="YOUR_DB_PASSWORD" # Use a strong password
FRESHRSS_PATH="/var/www/freshrss"
CADDY_CONFIG="/etc/caddy/Caddyfile"

# Dumping the database
echo "Dumping MariaDB database..."
mysqldump --user=$DB_USER --password=$DB_PASS $DB_NAME > "$BACKUP_DIR/$DB_NAME-$DATE.sql"

# Archiving FreshRSS data directory
echo "Archiving FreshRSS data directory..."
tar -czf "$BACKUP_DIR/freshrss_data-$DATE.tar.gz" -C "$FRESHRSS_PATH" data/ config/

# Copying Caddy configuration
echo "Copying Caddyfile..."
cp "$CADDY_CONFIG" "$BACKUP_DIR/Caddyfile-$DATE.conf"

# Deleting old backups (older than 7 days)
echo "Cleaning up old backups..."
find "$BACKUP_DIR" -type f -name ".sql" -mtime +7 -delete
find "$BACKUP_DIR" -type f -name ".tar.gz" -mtime +7 -delete
find "$BACKUP_DIR" -type f -name ".conf" -mtime +7 -delete

echo "Backup finished at $DATE"

chmod +x /opt/backups/freshrss/backup_freshrss.sh

crontab -e

0 3    /opt/backups/freshrss/backup_freshrss.sh >> /var/log/freshrss_backup.log 2>&1

This will run the script daily and log its output to /var/log/freshrss_backup.log.

3. Where to Store Backups

Storing backups on the same server as the live system is risky. In case of a server failure (e.g., disk failure), you will lose both the system and the backups. It is recommended to use remote storage:

• External S3-compatible service: AWS S3, DigitalOcean Spaces, Backblaze B2. For this, you can integrate s3cmd or rclone into the backup script.
• Separate VPS: If you have another VPS, you can configure rsync or scp to copy backups there via SSH.
• Local computer: For very small projects, you can periodically download backups to your computer manually or using a script.

For example, to copy to another server via SSH (after configuring passwordless SSH keys):

# Add to backup_freshrss.sh script after archiving
echo "Copying backups to remote server..."
rsync -avz "$BACKUP_DIR/" freshrssuser@REMOTE_IP:/path/to/remote/backups/

4. Updates: rolling vs. maintenance window

Keeping the system up-to-date is critical for security and stability.

• OS Updates (Ubuntu): Regularly run sudo apt update && sudo apt upgrade -y. For production systems, it is advisable to do this within a scheduled maintenance window to avoid unexpected failures. For a personal server, you can do it more frequently.
• PHP, MariaDB, Caddy Updates: These are also updated via apt upgrade. Sometimes, updates to these components may require manual intervention (e.g., merging configuration files).
• FreshRSS Updates:
  • Via Git: If you initially cloned the Git repository, updating involves a git pull in the FreshRSS directory, and then possibly running database migrations through the web interface.
  • Via Archive Download: If you installed FreshRSS from a ZIP archive, updating requires downloading the new version, extracting it, copying data/ and config/ from the old installation to the new one, then updating symlinks or changing the root directory in the Caddyfile.

Recommended Strategy:

1. Perform updates at a scheduled time.
2. Before major updates (especially major versions of PHP or FreshRSS), perform a full backup.
3. Read the changelogs of the programs being updated to be aware of possible changes or required manual actions.
4. For FreshRSS, after updating files, always access the web interface to ensure that no database migration is required.

Troubleshooting + FAQ

This section provides answers to frequently asked questions and solutions to common problems that may arise during FreshRSS installation and operation.

What is the minimum suitable VPS configuration?

For FreshRSS in single-user mode or for a small group of up to 5 users with a few hundred feeds, a VPS with 1 vCPU, 1 GB of RAM, and 20-30 GB of SSD storage will be minimally suitable. This configuration will be sufficient for stable operation, but with an increase in the number of feeds or users, it is recommended to increase RAM to 2 GB for better database and PHP-FPM performance.

What to choose — VPS or dedicated for this task?

For FreshRSS installation, a VPS is almost always sufficient. Dedicated servers are significantly more expensive and offer excessive resources for an RSS aggregator, unless you plan to serve thousands of users or integrate FreshRSS into a very large infrastructure with other resource-intensive services. A VPS provides an excellent balance of performance, flexibility, and cost for FreshRSS.

Why do I see a "502 Bad Gateway" error in the browser?

The "502 Bad Gateway" error usually indicates a problem with PHP-FPM. The web server (Caddy) cannot communicate with PHP-FPM or PHP-FPM is not processing requests.

What to check:

• Ensure that PHP-FPM is running: sudo systemctl status php8.3-fpm. If it's inactive, try starting it: sudo systemctl start php8.3-fpm.
• Check PHP-FPM logs: sudo journalctl -u php8.3-fpm. Look for errors that may indicate PHP configuration issues or insufficient memory.
• Ensure that Caddy is configured for the correct PHP-FPM socket (unix//run/php/php8.3-fpm.sock).

How to update FreshRSS to a new version?

If you followed this guide, FreshRSS was installed from an archive. To update:

1. Perform a backup: Be sure to perform a full backup of the database and the /var/www/freshrss/data directory.
2. Download the new version: Download the latest FreshRSS ZIP archive from the GitHub releases page.
3. Extract: Extract the new archive to a new temporary directory (e.g., /var/www/freshrss_new).
4. Transfer data: Copy the contents of the old /var/www/freshrss/data and /var/www/freshrss/config directories to the corresponding directories of the new installation.
5. Update links: Rename the old /var/www/freshrss directory (e.g., to freshrss_old) and rename the new freshrss_new directory to freshrss.
6. Set permissions: sudo chown -R www-data:www-data /var/www/freshrss && sudo chmod -R 755 /var/www/freshrss.
7. Restart Caddy: sudo systemctl reload caddy.
8. Complete in browser: Open FreshRSS in your browser. If a database migration is required, FreshRSS will prompt you to perform it.

My feeds are not updating automatically, what should I do?

This is most likely a Cron job issue.

What to check:

• Ensure that the Cron job for www-data exists and is correct: sudo crontab -u www-data -l.
• Verify that the path to the PHP interpreter and the actualize_script.php script is correct.
• Ensure that the www-data user has permissions to execute the script and write to the FreshRSS directories.
• Check system Cron logs: sudo grep CRON /var/log/syslog.
• Try running the script manually as the www-data user: sudo -u www-data php /var/www/freshrss/app/actualize_script.php and check the output.

How to add a new feed to FreshRSS?

In the FreshRSS web interface, go to the "Subscriptions" section, then click the "Add feed" button or the "+" icon. Paste the RSS feed URL into the field and click "Add". FreshRSS will attempt to detect and add the feed. You can also specify a category for the new feed.

How to configure FreshRSS for mobile app access?

FreshRSS supports the Fever API, which allows it to be used with many mobile RSS clients (e.g., Reeder, NetNewsWire, Lire).

1. In FreshRSS, go to "Settings" -> "Authentication".
2. Enable "API" and select "Fever API" as the method.
3. Create an "API Token" for each client or use an existing one.
4. In your mobile app, select "Fever" or "Self-hosted RSS" as the source and enter your FreshRSS address (https://yourdomain.com/p/api/fever) and API token.

Conclusions and Next Steps

Congratulations! You have successfully installed and configured FreshRSS on your VPS, creating a powerful, private, and fully controlled RSS aggregator. You now have a tool for efficient information stream management that does not depend on third-party services and protects your privacy. You have mastered not only the application installation but also the basic principles of web server, database, and PHP configuration, as well as ensuring security and backups.

Where to go next?

1. Explore FreshRSS functionality: Experiment with categories, filters, archiving rules, integration with other services (e.g., Instapaper or Wallabag for read-it-later), available in FreshRSS.
2. Optimization and monitoring: Monitor your VPS resource consumption using utilities like htop or grafana. If necessary, you can fine-tune PHP-FPM or Caddy for better performance or reduced memory consumption.
3. Additional services: You might want to deploy other useful self-hosted applications on your VPS, such as the Vaultwarden password manager, the Kanboard project management system, or the Nextcloud personal cloud storage.