Skip to content
Klutch.sh Docs

Deploying FreshRSS

Introduction

FreshRSS is a powerful, self-hosted RSS feed aggregator that allows you to stay up-to-date with your favorite websites and blogs in one convenient location. Built with PHP and MySQL/PostgreSQL support, FreshRSS provides a modern, responsive web interface for managing and reading your RSS feeds efficiently.

Deploying FreshRSS on Klutch.sh gives you a reliable, scalable platform for your RSS aggregation needs. This guide will walk you through deploying FreshRSS using a Dockerfile, configuring persistent storage for your feeds and data, setting up environment variables, and implementing production best practices. Whether you’re setting up FreshRSS for personal use or deploying it for a team, this comprehensive tutorial covers everything you need to know.

Why Deploy FreshRSS on Klutch.sh?

  • Automatic Dockerfile Detection: Klutch.sh automatically detects and uses your Dockerfile when present in the root directory
  • Built with Nixpacks: Leverage Nixpacks for efficient builds with customizable runtime and buildtime environment variables
  • Persistent Storage: Attach volumes to preserve your feed data, user preferences, and configurations across deployments
  • Secure by Default: Use environment variables for sensitive data like database credentials and API keys
  • Seamless GitHub Integration: Connect your GitHub repository for automated deployments
  • HTTP/TCP Traffic Support: Configure traffic routing based on your application needs

Prerequisites

Before you begin, ensure you have:

  • A Klutch.sh account (sign up here)
  • A GitHub repository for your FreshRSS deployment
  • Basic knowledge of Docker and RSS concepts
  • (Optional) A database instance (MySQL or PostgreSQL) for production deployments

Project Structure

Create a repository with the following structure:

freshrss-docker/
├── Dockerfile
├── .dockerignore
├── config/
│   └── config.php (optional)
└── README.md

This minimal structure allows Klutch.sh to automatically detect and build your FreshRSS application using the Dockerfile.

Step 1: Create Your Dockerfile

FreshRSS provides official Docker images that make deployment straightforward. Create a Dockerfile in the root of your repository:

    Basic Dockerfile

    For a quick start with SQLite (suitable for personal use):

    FROM freshrss/freshrss:latest
    

    # Set the working directory
    WORKDIR /var/www/FreshRSS
    

    # Expose the default FreshRSS port
    EXPOSE 80
    

    # The official image already includes the startup command
    # FreshRSS will be available on port 80

    Production Dockerfile with MySQL/PostgreSQL

    For production deployments with external database support:

    FROM freshrss/freshrss:latest
    

    # Install additional dependencies if needed
    RUN apt-get update && apt-get install -y \
        curl \
        && rm -rf /var/lib/apt/lists/*
    

    # Set the working directory
    WORKDIR /var/www/FreshRSS
    

    # Create a healthcheck to monitor application status
    HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
        CMD curl -f http://localhost:80/ || exit 1
    

    # Expose the default FreshRSS port
    EXPOSE 80
    

    # The entrypoint is inherited from the base image

    Advanced Dockerfile with Custom Configuration

    For advanced setups requiring custom configurations:

    FROM freshrss/freshrss:latest
    

    # Set environment for Apache
    ENV APACHE_RUN_USER www-data
    ENV APACHE_RUN_GROUP www-data
    ENV APACHE_LOG_DIR /var/log/apache2
    

    # Install additional tools for troubleshooting
    RUN apt-get update && apt-get install -y \
        vim \
        curl \
        wget \
        net-tools \
        && rm -rf /var/lib/apt/lists/*
    

    # Copy custom configuration if you have one
    # COPY config/config.php /var/www/FreshRSS/data/config.php
    

    # Set proper permissions
    RUN chown -R www-data:www-data /var/www/FreshRSS/data
    

    WORKDIR /var/www/FreshRSS
    

    # Health check
    HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
        CMD curl -f http://localhost:80/api/greader.php || exit 1
    

    EXPOSE 80

Step 2: Configure Environment Variables

FreshRSS requires several environment variables for optimal configuration. Set these in the Klutch.sh dashboard under your app’s environment settings.

    Basic Configuration (SQLite)

    For quick testing with SQLite:

    Terminal window
    # Application settings
    CRON_MIN=*/15
    TZ=America/New_York
    

    # Admin credentials (for initial setup)
    ADMIN_EMAIL=admin@example.com
    ADMIN_PASSWORD=secure_password_here
    ADMIN_API_PASSWORD=api_password_here

    Production Configuration (MySQL)

    For production deployments with MySQL:

    Terminal window
    # Database configuration
    DB_TYPE=mysql
    DB_HOST=mysql.example.com
    DB_PORT=3306
    DB_NAME=freshrss
    DB_USER=freshrss_user
    DB_PASSWORD=your_secure_password
    

    # Application settings
    CRON_MIN=*/15
    TZ=America/New_York
    BASE_URL=https://example-app.klutch.sh
    

    # Admin credentials
    ADMIN_EMAIL=admin@example.com
    ADMIN_PASSWORD=secure_password_here
    ADMIN_API_PASSWORD=api_password_here
    

    # Security settings
    TRUSTED_PROXY=10.0.0.0/8

    Production Configuration (PostgreSQL)

    For production deployments with PostgreSQL:

    Terminal window
    # Database configuration
    DB_TYPE=pgsql
    DB_HOST=postgres.example.com
    DB_PORT=5432
    DB_NAME=freshrss
    DB_USER=freshrss_user
    DB_PASSWORD=your_secure_password
    

    # Application settings
    CRON_MIN=*/15
    TZ=America/New_York
    BASE_URL=https://example-app.klutch.sh
    

    # Admin credentials
    ADMIN_EMAIL=admin@example.com
    ADMIN_PASSWORD=secure_password_here
    ADMIN_API_PASSWORD=api_password_here
    

    # Performance tuning
    PHP_MEMORY_LIMIT=256M
    MAX_EXECUTION_TIME=300

    Important Security Note: Never commit sensitive credentials to your repository. Always use Klutch.sh’s environment variables feature and mark them as secrets in the dashboard.

Step 3: Set Up Persistent Storage

FreshRSS requires persistent storage to maintain your feed data, user preferences, and configurations across deployments.

    Configure Persistent Volumes

    In the Klutch.sh dashboard, create and attach a persistent volume:

    1. Navigate to your app settings in the Klutch.sh dashboard at klutch.sh/app
    2. Go to the “Volumes” section
    3. Click “Add Volume” and configure:
      • Mount Path: /var/www/FreshRSS/data
      • Size: At least 5GB for basic usage, scale based on number of feeds

    This volume will store:

    • Feed subscriptions and article data
    • User accounts and preferences
    • Configuration files
    • Cache and temporary files
    • SQLite database (if using SQLite)

    Additional Volume for Extensions (Optional)

    If you plan to use FreshRSS extensions:

    • Mount Path: /var/www/FreshRSS/extensions
    • Size: 1GB

    Volume Backup Recommendations

    • Regularly back up your /var/www/FreshRSS/data volume
    • Store backups in a separate location or cloud storage
    • Test restoration procedures periodically
    • Consider automated backup scripts for production environments

Step 4: Deploy to Klutch.sh

Now that you have your Dockerfile and configurations ready, deploy FreshRSS to Klutch.sh.

    Push Your Repository

    Terminal window
    # Initialize git repository (if not already done)
    git init
    

    # Add your files
    git add Dockerfile .dockerignore README.md
    

    # Commit your changes
    git commit -m "Initial FreshRSS Dockerfile setup"
    

    # Push to GitHub
    git remote add origin https://github.com/your-username/freshrss-docker.git
    git branch -M main
    git push -u origin main

    Create App in Klutch.sh Dashboard

    1. Log in to klutch.sh/app
    2. Click “Create New App” or navigate to your project
    3. Connect your GitHub repository
    4. Klutch.sh will automatically detect the Dockerfile in your repository root

    Configure App Settings

    1. Traffic Type: Select HTTP (FreshRSS is a web application)
    2. Internal Port: Set to 80 (FreshRSS’s default port)
    3. Environment Variables: Add all the variables from Step 2
    4. Persistent Volumes: Attach the volume(s) configured in Step 3

    Deploy the Application

    1. Review your configuration settings
    2. Click “Deploy” to start the build process
    3. Klutch.sh will:
      • Clone your repository
      • Detect the Dockerfile automatically
      • Build the Docker image
      • Deploy the container with your configurations
      • Provision persistent storage

    Monitor Deployment

    • Watch the build logs in real-time
    • The deployment typically takes 2-5 minutes
    • Once complete, you’ll receive a URL like https://example-app.klutch.sh

Step 5: Initial Setup and Configuration

After deployment, complete the FreshRSS setup.

    Access FreshRSS

    Navigate to your deployed application URL (e.g., https://example-app.klutch.sh)

    Complete Initial Setup

    If this is your first deployment:

    1. Language Selection: Choose your preferred language
    2. System Check: FreshRSS will verify all requirements are met
    3. Database Configuration:
      • If using environment variables, these should auto-populate
      • Verify database connection is successful
    4. Admin Account: Create your administrator account
    5. Installation: Complete the setup process

    Add Your First Feeds

    1. Log in with your admin credentials
    2. Click “Subscription Management”
    3. Add RSS/Atom feeds by URL
    4. Organize feeds into categories
    5. Configure update intervals and display preferences

    Configure Auto-Update (Important)

    FreshRSS needs to periodically fetch new articles. The CRON_MIN environment variable handles this automatically in the official Docker image.

    To verify it’s working:

    1. Check the “System” → “About” page
    2. Look for the last update time
    3. Feeds should update based on your CRON_MIN setting (default: every 15 minutes)

Step 6: Database Setup (Production)

For production deployments, use an external database instead of SQLite.

    MySQL Setup

    Create a dedicated MySQL database and user:

    CREATE DATABASE freshrss CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'freshrss_user'@'%' IDENTIFIED BY 'your_secure_password';
    GRANT ALL PRIVILEGES ON freshrss.* TO 'freshrss_user'@'%';
    FLUSH PRIVILEGES;

    Then set these environment variables in Klutch.sh:

    Terminal window
    DB_TYPE=mysql
    DB_HOST=your-mysql-host
    DB_NAME=freshrss
    DB_USER=freshrss_user
    DB_PASSWORD=your_secure_password

    PostgreSQL Setup

    Create a dedicated PostgreSQL database and user:

    CREATE DATABASE freshrss;
    CREATE USER freshrss_user WITH PASSWORD 'your_secure_password';
    GRANT ALL PRIVILEGES ON DATABASE freshrss TO freshrss_user;

    Then set these environment variables in Klutch.sh:

    Terminal window
    DB_TYPE=pgsql
    DB_HOST=your-postgres-host
    DB_NAME=freshrss
    DB_USER=freshrss_user
    DB_PASSWORD=your_secure_password

    Database Backup Strategy

    Implement regular backups:

    For MySQL:

    Terminal window
    # Use -p without password to prompt securely (recommended)
    mysqldump -h $DB_HOST -u $DB_USER -p $DB_NAME > freshrss-backup-$(date +%Y%m%d).sql
    

    # Or use a credentials file for automation
    mysqldump --defaults-extra-file=/path/to/.my.cnf $DB_NAME > freshrss-backup-$(date +%Y%m%d).sql

    For PostgreSQL:

    Terminal window
    # Use PGPASSWORD environment variable or .pgpass file for secure authentication
    pg_dump -h $DB_HOST -U $DB_USER $DB_NAME > freshrss-backup-$(date +%Y%m%d).sql

    Store backups securely and test restoration procedures regularly.

Step 7: Advanced Configuration

Customize FreshRSS for optimal performance and features.

    API Access

    FreshRSS provides a Google Reader-compatible API for mobile apps:

    1. Enable API in settings
    2. Generate an API password
    3. Use the API endpoint: https://example-app.klutch.sh/api/greader.php
    4. Compatible apps include: Reeder, FeedMe, News+, and many others

    Extensions and Customization

    Add FreshRSS extensions for additional functionality:

    1. Clone extensions to a local directory
    2. Add them to your repository in an extensions/ folder
    3. Update your Dockerfile to copy extensions:
    COPY extensions/ /var/www/FreshRSS/extensions/
    RUN chown -R www-data:www-data /var/www/FreshRSS/extensions

    Popular extensions include:

    • Reddit Image
    • YouTube
    • Tumblr GDPR
    • Fever API

    Performance Tuning

    Optimize FreshRSS for larger feed collections:

    Environment Variables:

    Terminal window
    PHP_MEMORY_LIMIT=512M
    MAX_EXECUTION_TIME=300
    OPCACHE_ENABLE=1

    Dockerfile additions:

    # Enable and configure OPcache
    RUN echo "opcache.enable=1" >> /usr/local/etc/php/conf.d/opcache.ini && \
        echo "opcache.memory_consumption=128" >> /usr/local/etc/php/conf.d/opcache.ini && \
        echo "opcache.max_accelerated_files=10000" >> /usr/local/etc/php/conf.d/opcache.ini

    Custom Themes

    Apply custom themes to personalize FreshRSS:

    1. Add theme files to your repository
    2. Copy them in your Dockerfile:
    COPY themes/ /var/www/FreshRSS/data/themes/
    RUN chown -R www-data:www-data /var/www/FreshRSS/data/themes

Step 8: Security Best Practices

Secure your FreshRSS deployment for production use.

    Authentication and Access Control

    1. Strong Passwords: Use complex passwords for admin accounts
    2. HTTPS Only: Klutch.sh provides automatic HTTPS for all deployments
    3. Regular Updates: Keep FreshRSS updated by rebuilding with the latest image
    4. API Security: Use separate API passwords from your login password

    Environment Security

    1. Secret Management: Store all sensitive data in Klutch.sh environment variables
    2. Network Security: Use private networking for database connections when possible
    3. Database Credentials: Rotate database passwords periodically
    4. Access Logs: Monitor access logs for suspicious activity

    Backup and Recovery

    1. Automated Backups: Schedule regular backups of volumes and database
    2. Off-site Storage: Store backups in a separate location from your deployment
    3. Test Restores: Regularly test your backup restoration process
    4. Version Control: Keep your Dockerfile and configurations in version control

    Security Headers

    Add security headers via Apache configuration (create a custom config):

    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-Content-Type-Options "nosniff"
    Header always set X-XSS-Protection "1; mode=block"
    Header always set Referrer-Policy "strict-origin-when-cross-origin"

Step 9: Monitoring and Maintenance

Keep your FreshRSS deployment healthy and performant.

    Health Monitoring

    Monitor key metrics in Klutch.sh dashboard:

    • CPU Usage: Should remain under 50% for normal operations
    • Memory Usage: Depends on feed count; typically 128-512MB
    • Disk Usage: Monitor volume usage, especially with many feeds
    • Network Traffic: Track bandwidth usage for feed fetching

    Application Monitoring

    Within FreshRSS:

    1. Check “System” → “About” for last update time
    2. Monitor feed update success rates
    3. Review error logs at /var/www/FreshRSS/data/users/_/log.txt
    4. Track database size growth

    Maintenance Tasks

    Regular maintenance ensures optimal performance:

    1. Feed Cleanup: Remove inactive or broken feeds
    2. Article Purging: Configure retention policies for old articles
    3. Database Optimization: Run optimization queries monthly
    4. Log Rotation: Clean up old log files
    5. Extension Updates: Keep extensions updated

    Troubleshooting Common Issues

    Feed Update Failures:

    • Check cron job is running (CRON_MIN environment variable)
    • Verify network connectivity to feed sources
    • Review logs for specific error messages

    Database Connection Errors:

    • Verify database credentials in environment variables
    • Check network connectivity to database host
    • Ensure database server is running and accessible

    Performance Issues:

    • Increase PHP memory limit
    • Optimize database indexes
    • Reduce feed update frequency
    • Consider using PostgreSQL instead of SQLite

    Volume Permission Issues:

    • Ensure proper ownership: chown -R www-data:www-data /var/www/FreshRSS/data
    • Check volume mount paths match configuration

Step 10: Scaling and Optimization

Grow your FreshRSS deployment as your needs expand.

    Vertical Scaling

    Increase resources for your application:

    1. In Klutch.sh dashboard, adjust instance size
    2. Increase memory for larger feed collections
    3. Add more CPU for faster feed processing
    4. Expand volume size as article database grows

    Database Optimization

    For large deployments (100+ feeds):

    1. Use PostgreSQL: Better performance than MySQL for read-heavy workloads
    2. Enable Connection Pooling: Reduce database connection overhead
    3. Index Optimization: Ensure proper indexes on frequently queried columns
    4. Query Caching: Enable database query caching

    Feed Management Strategy

    Optimize feed collection:

    1. Prioritize Feeds: Update important feeds more frequently
    2. Remove Dead Feeds: Regularly audit and remove inactive feeds
    3. Category Organization: Group related feeds for easier management
    4. Selective Updates: Update different feed groups at different intervals

    Caching Strategy

    Implement effective caching:

    1. OPcache: Enable PHP OPcache for better performance
    2. Static Assets: FreshRSS automatically caches static assets
    3. Database Queries: Configure query result caching
    4. HTTP Caching: Set appropriate cache headers

Using Nixpacks Customization

Since Klutch.sh uses Nixpacks for builds, you can customize the build and runtime behavior.

    Custom Start Command

    If you need to modify the default start command, use runtime environment variables:

    Terminal window
    # Set custom start command via Nixpacks
    NIXPACKS_START_CMD="apache2-foreground"

    Custom Build Command

    For build-time customizations:

    Terminal window
    # Custom build command
    NIXPACKS_BUILD_CMD="apt-get update && apt-get install -y custom-package"

    PHP Configuration

    Customize PHP settings via environment variables:

    Terminal window
    PHP_MEMORY_LIMIT=512M
    PHP_MAX_EXECUTION_TIME=300
    PHP_UPLOAD_MAX_FILESIZE=50M
    PHP_POST_MAX_SIZE=50M

Migrating from Existing FreshRSS Installation

If you’re migrating from an existing FreshRSS installation:

    Export Your Data

    From your existing installation:

    1. Navigate to “System” → “Data management”
    2. Export your OPML file (contains feed subscriptions)
    3. Export starred articles if needed
    4. Backup your database

    Import to Klutch.sh Deployment

    1. Deploy FreshRSS on Klutch.sh following this guide
    2. Complete initial setup
    3. Import OPML file via “Subscription management” → “Import/Export”
    4. For database migration:
      • Export from old database: mysqldump ...
      • Import to new database: mysql ... < backup.sql
    5. Copy custom extensions or themes if used

    Verify Migration

    1. Check all feeds are present and updating
    2. Verify user accounts and preferences
    3. Test starred articles and read/unread status
    4. Validate custom categories and filters

Local Development with Docker Compose

For local testing before deploying to Klutch.sh, use Docker Compose:

version: '3.8'


services:
  freshrss:
    build: .
    ports:
      - "8080:80"
    environment:
      - CRON_MIN=*/15
      - TZ=America/New_York
      - DB_TYPE=mysql
      - DB_HOST=db
      - DB_NAME=freshrss
      - DB_USER=freshrss
      - DB_PASSWORD=<your-secure-db-password>
    volumes:
      - freshrss-data:/var/www/FreshRSS/data
    depends_on:
      - db


  db:
    image: mysql:8
    environment:
      - MYSQL_ROOT_PASSWORD=<your-secure-root-password>
      - MYSQL_DATABASE=freshrss
      - MYSQL_USER=freshrss
      - MYSQL_PASSWORD=<your-secure-db-password>
    volumes:
      - mysql-data:/var/lib/mysql


volumes:
  freshrss-data:
  mysql-data:

Run locally with:

Terminal window
docker-compose up -d

Access at http://localhost:8080

Note: Docker Compose is not supported by Klutch.sh for deployment. Use this only for local development and testing.

Troubleshooting Guide

Common issues and solutions:

    Dockerfile Not Detected

    Problem: Klutch.sh doesn’t detect your Dockerfile

    Solution:

    • Ensure Dockerfile is in the repository root
    • Check filename is exactly Dockerfile (case-sensitive)
    • Verify file is committed and pushed to GitHub

    Port Configuration Issues

    Problem: Application not accessible after deployment

    Solution:

    • Verify internal port is set to 80 in Klutch.sh dashboard
    • Ensure traffic type is set to HTTP
    • Check container logs for binding errors

    Database Connection Failures

    Problem: Cannot connect to database

    Solution:

    • Verify environment variables are set correctly
    • Check database host is accessible from Klutch.sh
    • Ensure database user has proper permissions
    • Test connection credentials separately

    Volume Mount Issues

    Problem: Data not persisting between deployments

    Solution:

    • Verify volume mount path is /var/www/FreshRSS/data
    • Check volume is attached in Klutch.sh dashboard
    • Ensure proper permissions on mounted directory

    Feed Update Problems

    Problem: Feeds not updating automatically

    Solution:

    • Check CRON_MIN environment variable is set
    • Verify no errors in FreshRSS logs
    • Test manual feed update in the UI
    • Ensure server can access external feed URLs

    Performance Issues

    Problem: Slow application performance

    Solution:

    • Increase PHP memory limit
    • Switch from SQLite to MySQL/PostgreSQL
    • Enable OPcache in PHP configuration
    • Reduce number of feeds or increase update interval
    • Scale up instance size in Klutch.sh

Example Production Deployment

Complete example for a production FreshRSS deployment:

Dockerfile:

FROM freshrss/freshrss:1.23.1


RUN apt-get update && apt-get install -y \
    curl \
    vim \
    && rm -rf /var/lib/apt/lists/*


WORKDIR /var/www/FreshRSS


RUN echo "opcache.enable=1" >> /usr/local/etc/php/conf.d/opcache.ini && \
    echo "opcache.memory_consumption=256" >> /usr/local/etc/php/conf.d/opcache.ini


HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD curl -f http://localhost:80/api/greader.php || exit 1


EXPOSE 80

Environment Variables:

Terminal window
DB_TYPE=mysql
DB_HOST=mysql.production.klutch.sh
DB_PORT=3306
DB_NAME=freshrss_prod
DB_USER=freshrss_user
DB_PASSWORD=<secret>


CRON_MIN=*/10
TZ=America/New_York
BASE_URL=https://rss.example.com


ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=<secret>
ADMIN_API_PASSWORD=<secret>


PHP_MEMORY_LIMIT=512M
MAX_EXECUTION_TIME=300


TRUSTED_PROXY=10.0.0.0/8

Volume Configuration:

  • Mount Path: /var/www/FreshRSS/data
  • Size: 20GB

Traffic Configuration:

  • Type: HTTP
  • Internal Port: 80

Additional Resources

Conclusion

Deploying FreshRSS on Klutch.sh with a Dockerfile provides a robust, scalable solution for RSS feed aggregation. By following this guide, you’ve learned how to:

  • Create an optimized Dockerfile for FreshRSS
  • Configure environment variables and secrets securely
  • Set up persistent storage for long-term data retention
  • Deploy using Klutch.sh’s automatic Dockerfile detection
  • Implement security best practices
  • Monitor and maintain your deployment
  • Troubleshoot common issues
  • Scale your deployment as needs grow

FreshRSS on Klutch.sh offers the perfect balance of self-hosting control with the convenience of managed infrastructure. Your RSS feeds are now centralized, secure, and accessible from anywhere with automatic HTTPS, persistent storage, and easy scaling capabilities.

For additional help or questions, refer to the FreshRSS community resources and Klutch.sh documentation linked above.