Skip to content
Klutch.sh Docs

Deploying a CommaFeed App

Introduction

CommaFeed is a free, open-source, self-hosted RSS reader inspired by Google Reader. Built with Java and AngularJS, CommaFeed provides a clean, responsive interface for organizing and reading your favorite RSS and Atom feeds. It’s perfect for individuals and teams who want to aggregate news, blogs, podcasts, and content from across the web in one centralized location.

Deploying CommaFeed on Klutch.sh gives you a reliable, production-ready RSS reader with automated deployments from GitHub, persistent storage for your feed data and user preferences, and a scalable infrastructure for hosting your personal or team feed aggregator. Whether you’re building a personal news reader, creating a content curation platform, or replacing a commercial RSS service, this guide walks you through deploying CommaFeed using Docker to ensure a reproducible, secure, and maintainable setup.

This guide covers everything you need to successfully deploy CommaFeed on Klutch.sh: from creating your production-ready Dockerfile to configuring PostgreSQL database connections, setting up persistent volumes for application data, managing environment variables securely, configuring the internal port routing, and implementing best practices for security, performance, and scalability.

Prerequisites

Before you begin deploying CommaFeed on Klutch.sh, ensure you have the following:

  • A Klutch.sh account (access the dashboard here)
  • A GitHub repository for your CommaFeed deployment project
  • Basic familiarity with Docker, environment variables, and database management
  • A PostgreSQL database (you can provision one on Klutch.sh or use an external managed database service)
  • Understanding of Java applications (helpful but not required)

What You’ll Deploy

By the end of this guide, you’ll have:

  • A fully functional CommaFeed RSS reader running on Klutch.sh
  • PostgreSQL database connectivity for storing feeds, articles, and user data
  • Secure environment variable configuration for credentials and API keys
  • Production-ready setup with proper security configurations
  • A Docker-based deployment that’s reproducible and easy to maintain
  • HTTP traffic routing configured properly for web access
  • Optional persistent storage for application logs and configurations

Understanding CommaFeed Architecture

CommaFeed is built with Java and requires:

  • Java Runtime Environment (JRE) 17 or higher for running the application
  • PostgreSQL 12+ database for storing feeds, articles, user accounts, and preferences
  • Web server built into the application (embedded Jetty server)
  • Feed fetching engine that periodically retrieves and updates RSS/Atom feeds
  • File storage for application configurations and logs (optional)

The application runs on port 8082 by default. For Klutch.sh deployments with HTTP traffic, you’ll configure the internal port to 8082, and traffic will be accessible through your assigned domain.

1. Prepare Your CommaFeed Repository

    1. Create a new GitHub repository for your CommaFeed deployment.

    2. In your repository root, you’ll create a Dockerfile that defines the container image for CommaFeed. This ensures reproducible builds and makes deployment consistent.

    3. Keep sensitive data (database credentials, application secrets, admin passwords) out of your repository. We’ll use Klutch.sh environment variables to manage secrets securely.

    4. Organize your repository structure:

      commafeed-deployment/
      ├── Dockerfile
      ├── config.yml (optional, for custom configurations)
      ├── .dockerignore
      └── README.md

    5. Create a .dockerignore file to exclude unnecessary files from the Docker build:

      .git
      .github
      .env
      .env.*
      *.log
      logs/
      README.md

For more details on setting up your repository and connecting to GitHub, refer to the Klutch.sh Quick Start Guide.

2. Sample Dockerfile for CommaFeed

Below is a production-ready Dockerfile that sets up CommaFeed with PostgreSQL support. This Dockerfile uses the official CommaFeed Docker image approach and configures it for Klutch.sh deployment.

FROM eclipse-temurin:17-jre-alpine


# Set working directory
WORKDIR /app


# Install required packages
RUN apk add --no-cache curl postgresql-client


# Download CommaFeed latest release
ARG COMMAFEED_VERSION=2.7.0
RUN curl -L https://github.com/Athou/commafeed/releases/download/${COMMAFEED_VERSION}/commafeed.jar -o commafeed.jar


# Create directory for logs
RUN mkdir -p /app/logs


# Expose the application port
EXPOSE 8082


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8082/ || exit 1


# Start CommaFeed
CMD ["java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "commafeed.jar", "server"]

Dockerfile Explanation

  • Base Image: Uses eclipse-temurin:17-jre-alpine which includes Java 17 runtime on a lightweight Alpine Linux base
  • Package Installation: Installs curl for health checks and postgresql-client for database connectivity testing
  • CommaFeed Download: Downloads a specific version of CommaFeed from GitHub releases for reproducibility
  • Logs Directory: Creates a directory for application logs
  • Port: Exposes port 8082 for HTTP traffic
  • Health Check: Configures Docker health check to monitor application status
  • Startup Command: Runs CommaFeed in server mode with optimized JVM settings

3. CommaFeed Configuration

CommaFeed can be configured through environment variables or a config.yml file. For Klutch.sh deployments, we’ll primarily use environment variables for flexibility and security.

Optional: Custom Configuration File

If you need advanced configuration options, create a config.yml file in your repository:

# CommaFeed Configuration
app:
  # Application name shown in the UI
  name: CommaFeed
  # Public URL of your CommaFeed instance
  publicUrl: https://example-app.klutch.sh
  # Allow user registration
  allowRegistrations: false
  # Session timeout in minutes
  sessionTimeout: 30


database:
  # Database configuration (will be overridden by environment variables)
  driverClass: org.postgresql.Driver
  url: ${DATABASE_URL}
  user: ${DATABASE_USER}
  password: ${DATABASE_PASSWORD}


feedRefresh:
  # How often to check for new articles (in minutes)
  backgroundRefreshInterval: 5


security:
  # Enable HTTPS redirect (handled by Klutch.sh)
  httpsRedirect: false

If you include this file, update your Dockerfile to copy it:

# Add after the RUN mkdir -p /app/logs line
COPY config.yml /app/config.yml

4. Database Setup

CommaFeed requires a PostgreSQL database to store feeds, articles, user accounts, and preferences. You can use a managed PostgreSQL service or deploy your own PostgreSQL container.

Option A: Using an External PostgreSQL Service

If you’re using a managed PostgreSQL service (like AWS RDS, DigitalOcean Managed Databases, or Supabase):

    1. Create a new PostgreSQL database instance through your provider.

    2. Create a dedicated database for CommaFeed (e.g., commafeed_db).

    3. Create a dedicated PostgreSQL user with full privileges on the CommaFeed database:

      CREATE DATABASE commafeed_db;
      CREATE USER commafeed_user WITH PASSWORD 'your_secure_password';
      GRANT ALL PRIVILEGES ON DATABASE commafeed_db TO commafeed_user;

    4. Note the database host, port, database name, username, and password for configuration in Klutch.sh.

    5. Ensure network connectivity between your Klutch.sh app and the database (configure security groups/firewall rules as needed).

Option B: Using Klutch.sh PostgreSQL

    1. In the Klutch.sh dashboard, create a new app for PostgreSQL.

    2. Use a PostgreSQL Docker image (e.g., postgres:15-alpine).

    3. Configure it with TCP traffic type on port 8000 (which internally routes to PostgreSQL’s port 5432).

    4. Set the internal port to 5432 for the PostgreSQL container.

    5. Configure environment variables for PostgreSQL:

      • POSTGRES_DB=commafeed_db
      • POSTGRES_USER=commafeed_user
      • POSTGRES_PASSWORD=your_secure_password

    6. Attach a persistent volume to /var/lib/postgresql/data to ensure data persists across deployments.

    7. Note the connection details to use in your CommaFeed configuration.

For more information about deploying databases on Klutch.sh, see the PostgreSQL deployment guide.

5. Environment Variables Configuration

Configure the following environment variables in the Klutch.sh dashboard under your app’s settings. These variables are essential for CommaFeed to connect to the database and operate correctly.

Required Environment Variables

Terminal window
# Database Configuration
DATABASE_URL=jdbc:postgresql://your-postgres-host:5432/commafeed_db
DATABASE_USER=commafeed_user
DATABASE_PASSWORD=your_secure_database_password


# Application Configuration
COMMAFEED_APP_PUBLICURL=https://example-app.klutch.sh
COMMAFEED_APP_ALLOWREGISTRATIONS=false
COMMAFEED_APP_NAME=CommaFeed


# Admin Account (for initial setup)
COMMAFEED_ADMIN_PASSWORD=your_secure_admin_password

Environment Variables Explanation

  • DATABASE_URL: JDBC connection string for PostgreSQL. Format: jdbc:postgresql://HOST:PORT/DATABASE_NAME
  • DATABASE_USER: PostgreSQL username created for CommaFeed
  • DATABASE_PASSWORD: PostgreSQL password for the CommaFeed user
  • COMMAFEED_APP_PUBLICURL: The public URL where your CommaFeed instance will be accessible (e.g., https://example-app.klutch.sh)
  • COMMAFEED_APP_ALLOWREGISTRATIONS: Set to false to disable public registration, true to allow anyone to create accounts
  • COMMAFEED_APP_NAME: The name displayed in the CommaFeed interface
  • COMMAFEED_ADMIN_PASSWORD: Password for the default admin account (username: admin)

Optional Environment Variables

Terminal window
# Feed Refresh Configuration
COMMAFEED_FEEDREFRESH_BACKGROUNDREFRESHINTERVAL=5


# Session Configuration
COMMAFEED_APP_SESSIONTIMEOUT=30


# Email Configuration (for password resets)
COMMAFEED_SMTP_HOST=smtp.example.com
COMMAFEED_SMTP_PORT=587
COMMAFEED_SMTP_TLS=true
COMMAFEED_SMTP_USERNAME=your_smtp_username
COMMAFEED_SMTP_PASSWORD=your_smtp_password
COMMAFEED_SMTP_FROM=noreply@example.com

Security Best Practice: Mark sensitive values like DATABASE_PASSWORD and COMMAFEED_ADMIN_PASSWORD as secrets in Klutch.sh to prevent them from being logged or displayed in the UI.

6. Persistent Storage Configuration

While CommaFeed stores most data in the PostgreSQL database, you may want persistent storage for application logs and any custom configurations.

    1. In the Klutch.sh dashboard, navigate to your app configuration.

    2. Under the Volumes section, add a new persistent volume.

    3. Set the mount path to /app/logs for storing application logs.

    4. Set the volume size based on your expected log retention needs (start with 1GB).

Note: The mount path is where your log data will persist across deployments. This is optional but recommended for troubleshooting and monitoring.

For more information about volumes, see the Klutch.sh Volumes Guide.

7. Deploying to Klutch.sh

Now that you have your repository configured with the Dockerfile and understanding of the required environment variables, let’s deploy CommaFeed to Klutch.sh.

    1. Push your repository to GitHub: Ensure your Dockerfile, optional config.yml, .dockerignore, and README.md are committed and pushed to your GitHub repository.

    2. Access the Klutch.sh dashboard: Log in to klutch.sh/app.

    3. Create a new project (if you haven’t already): Projects help organize related apps and resources.

    4. Create a new app:

      • Click “New App” or “Create App”
      • Select your GitHub repository containing the CommaFeed Dockerfile
      • Klutch.sh will automatically detect the Dockerfile in your root directory

    5. Configure the app settings:

      • Name: Give your app a meaningful name (e.g., “commafeed-rss”)
      • Branch: Select the Git branch to deploy (usually main or master)

    6. Set up persistent volumes (optional but recommended):

      • Navigate to the Volumes section in the app configuration
      • Add a volume with mount path: /app/logs
      • Set size: Start with 1GB (adjust based on your needs)

    7. Configure environment variables:

      • Add all the required environment variables listed in Section 5
      • Mark sensitive values (DATABASE_PASSWORD, COMMAFEED_ADMIN_PASSWORD) as secrets
      • Ensure COMMAFEED_APP_PUBLICURL matches your intended domain

    8. Configure network settings:

      • Select HTTP traffic type (not TCP)
      • Set the internal port to 8082 (the port CommaFeed listens on inside the container)

    9. Review and deploy:

      • Review all settings to ensure everything is configured correctly
      • Click “Create” or “Deploy” to start the build and deployment process

    10. Monitor the deployment:

      • Watch the build logs to ensure the Docker image builds successfully
      • Once deployed, the app status should show as “Running”
      • Check the runtime logs for any errors or issues

    11. Access your CommaFeed instance:

      • Navigate to your app URL (e.g., https://example-app.klutch.sh)
      • You should see the CommaFeed login page
      • Log in with username admin and the password you set in COMMAFEED_ADMIN_PASSWORD

For more detailed deployment instructions, see the Klutch.sh Quick Start Guide.

8. Initial CommaFeed Setup

After your deployment is successful and the app is running:

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

    2. Log in with the admin credentials:

      • Username: admin
      • Password: The password you set in COMMAFEED_ADMIN_PASSWORD environment variable

    3. Important: Change the admin password immediately:

      • Click on the settings icon (gear icon) in the top-right
      • Go to “Profile” or “Settings”
      • Update your password to something secure and unique

    4. Configure application settings:

      • Set your preferred theme (light or dark mode)
      • Configure reading preferences (mark as read on scroll, etc.)
      • Set up keyboard shortcuts if desired

    5. Add your first RSS feeds:

      • Click the “Add subscription” button (+ icon)
      • Enter the RSS/Atom feed URL
      • Organize feeds into categories for better management
      • CommaFeed will immediately fetch articles from your feeds

    6. (Optional) Create additional user accounts:

      • If you disabled public registration, you can manually create accounts
      • Go to Admin settings to manage users

    7. Configure feed refresh settings:

      • Adjust how often CommaFeed checks for new articles
      • Balance between freshness and server load

9. Custom Domain Configuration

To use a custom domain with your CommaFeed instance instead of the default Klutch.sh subdomain:

    1. In the Klutch.sh dashboard, navigate to your CommaFeed app.

    2. Go to the Domains section and add your custom domain (e.g., feeds.example.com).

    3. Klutch.sh will provide you with DNS configuration instructions:

      • Add a CNAME record pointing to your Klutch.sh app URL, or
      • Add an A record pointing to the provided IP address

    4. Update the COMMAFEED_APP_PUBLICURL environment variable to match your custom domain:

      Terminal window
      COMMAFEED_APP_PUBLICURL=https://feeds.example.com

    5. Redeploy the app to apply the new configuration.

    6. Wait for DNS propagation (can take up to 48 hours but usually much faster).

    7. Klutch.sh automatically provisions and manages SSL/TLS certificates for your custom domain.

    8. Once DNS propagates, access CommaFeed at your custom domain with HTTPS enabled.

For more information, see the Custom Domains Guide.

10. Backup and Maintenance

Regular backups are essential for protecting your feed data and user preferences.

Database Backups

Use pg_dump to create regular database backups:

Terminal window
pg_dump -h $DATABASE_HOST -U $DATABASE_USER -d commafeed_db > commafeed-backup-$(date +%F).sql

Automate this with a cron job or scheduled task, and store backups in object storage (S3, Backblaze B2, etc.).

Backup Schedule Recommendations

  • Daily backups: For active CommaFeed instances with multiple users
  • Weekly backups: For personal instances with minimal changes
  • Monthly backups: Archive backups for long-term retention
  • Pre-upgrade backups: Always backup before updating CommaFeed

Restoration

To restore from a backup:

    1. Stop the CommaFeed application temporarily.

    2. Restore the database:

      Terminal window
      psql -h $DATABASE_HOST -U $DATABASE_USER -d commafeed_db < commafeed-backup-2024-01-15.sql

    3. Restart the CommaFeed application.

    4. Verify that feeds and articles are restored correctly.

11. Security Best Practices

Application Security

  • Change default admin password immediately after first login
  • Disable public registration if CommaFeed is for personal or team use only
  • Use strong passwords: Enforce strong password policies for all users
  • Regular updates: Keep CommaFeed updated to the latest version for security patches
  • Limit admin access: Only grant admin privileges to trusted users

Database Security

  • Use strong database passwords with at least 20 characters
  • Limit database access: Only allow connections from your CommaFeed app
  • Enable SSL/TLS for database connections when possible
  • Regular backups: Automate database backups to prevent data loss
  • Rotate credentials: Periodically change database passwords

Infrastructure Security

  • HTTPS only: Always use HTTPS for production deployments (automatic with Klutch.sh)
  • Environment variables: Never commit secrets to your repository
  • Minimal permissions: Grant only necessary permissions to database users
  • Monitor logs: Regularly review application and access logs for suspicious activity
  • Rate limiting: Consider implementing rate limiting for API endpoints if exposing CommaFeed publicly

Feed Security

  • Validate feed URLs: Be cautious about adding untrusted feed sources
  • Monitor resource usage: Some feeds may be resource-intensive or malicious
  • Content filtering: Use CommaFeed’s filtering features to manage content
  • Review subscriptions: Regularly audit and remove unused or inactive feeds

12. Performance Optimization

Application Optimization

  • Database indexing: Ensure proper database indexes for query performance
  • Feed refresh tuning: Adjust background refresh intervals based on your needs (5-15 minutes is typical)
  • Memory allocation: Increase JVM heap size if needed by modifying the Dockerfile CMD: 
    CMD ["java", "-Xmx512m", "-Xms256m", "-Djava.security.egd=file:/dev/./urandom", "-jar", "commafeed.jar", "server"]
  • Database connection pooling: Configure appropriate pool sizes for your workload
  • Article retention: Configure how long to keep old articles to manage database size

Infrastructure Optimization

  • Scale vertically: Increase CPU and memory if the app becomes slow under load
  • Database optimization: Use appropriate PostgreSQL configuration for your workload
  • Monitoring: Set up monitoring for CPU, memory, and response time metrics
  • Database maintenance: Run regular VACUUM and ANALYZE operations on PostgreSQL

Feed Management Best Practices

  • Organize feeds into categories: Makes management easier and improves user experience
  • Remove inactive feeds: Unsubscribe from feeds that haven’t updated in months
  • Monitor feed health: Identify and fix or remove broken feeds
  • Batch operations: Use bulk actions for marking articles as read or managing subscriptions

13. Troubleshooting

Common Issues and Solutions

Issue: “Database Connection Failed” Error

Solution:

  • Verify database credentials in environment variables
  • Check network connectivity between app and database
  • Ensure database user has proper privileges
  • Test connection manually: psql -h $DATABASE_HOST -U $DATABASE_USER -d commafeed_db
  • Verify the JDBC URL format is correct

Issue: Application Won’t Start or Crashes

Solution:

  • Check application logs in the Klutch.sh dashboard
  • Verify Java version compatibility (requires Java 17+)
  • Ensure database is running and accessible
  • Check for port conflicts on 8082
  • Verify environment variables are set correctly
  • Review health check status

Issue: Feeds Not Updating

Solution:

  • Check the background refresh interval setting
  • Verify CommaFeed can access external feed URLs
  • Check application logs for feed fetch errors
  • Test feed URLs manually to ensure they’re valid and accessible
  • Consider increasing refresh interval if hitting rate limits

Issue: 502 Bad Gateway or App Not Responding

Solution:

  • Verify internal port is set to 8082
  • Check that the Java process is running inside the container
  • Review application logs for startup errors
  • Ensure health check is passing
  • Verify database connectivity

Issue: Cannot Log In After Deployment

Solution:

  • Verify COMMAFEED_ADMIN_PASSWORD environment variable is set
  • Try resetting the admin password through database if needed
  • Check application logs for authentication errors
  • Clear browser cache and cookies
  • Verify the public URL is configured correctly

Debugging Tips

View Application Logs:

Check logs in the Klutch.sh dashboard or inside the container:

Terminal window
# Inside the container
tail -f /app/logs/commafeed.log

Test Database Connectivity:

Terminal window
# From within the container
psql -h $DATABASE_HOST -U $DATABASE_USER -d commafeed_db -c "SELECT version();"

Check Java Process:

Terminal window
# Inside the container
ps aux | grep java

Verify Environment Variables:

Terminal window
# Inside the container
env | grep COMMAFEED

14. Updating CommaFeed

To update CommaFeed to a newer version:

    1. Backup your database before updating (see Section 10).

    2. Update the COMMAFEED_VERSION argument in your Dockerfile to the desired version:

      ARG COMMAFEED_VERSION=2.8.0

    3. Review the CommaFeed release notes for breaking changes or migration steps.

    4. Commit and push the change to your GitHub repository.

    5. Klutch.sh will automatically trigger a new build with the updated version.

    6. Monitor the deployment logs for any issues.

    7. Test the updated version thoroughly:

      • Verify login works
      • Check that existing feeds are intact
      • Test adding new feeds
      • Verify article fetching is working

    8. If issues occur, you can quickly rollback by reverting the Dockerfile change and redeploying.

Note: CommaFeed handles database migrations automatically on startup, so no manual migration steps are typically required.

15. Advanced Features and Integrations

API Access

CommaFeed provides a REST API for programmatic access:

  • API documentation is available at https://example-app.klutch.sh/api
  • Generate API keys in your user profile settings
  • Use API for integrations with other tools and automation

Mobile Access

CommaFeed’s responsive design works well on mobile browsers, but you can also use third-party mobile RSS reader apps that support the Fever API:

  • Configure Fever API access in CommaFeed settings
  • Use compatible mobile apps like Reeder, Unread, or Fiery Feeds
  • Access your feeds from any device with API credentials

OPML Import/Export

Import feeds from other RSS readers or export your subscriptions:

  • Go to Settings → Import/Export
  • Upload OPML file to import feeds from Google Reader, Feedly, or other services
  • Export OPML to backup your subscriptions or move to another reader

Browser Extensions

Use browser bookmarklets or extensions to quickly add feeds:

  • Create a bookmarklet for “Subscribe in CommaFeed”
  • Use browser extensions for one-click feed detection and subscription
  • Configure keyboard shortcuts for faster navigation

Keyboard Shortcuts

CommaFeed supports keyboard shortcuts for power users:

  • j/k - Navigate between articles
  • v - Open article in new tab
  • m - Mark as read/unread
  • s - Star article
  • Shift+A - Mark all as read
  • Configure custom shortcuts in settings

16. Feed Discovery and Management Tips

Finding Quality RSS Feeds

  • News sites: Most major news outlets provide RSS feeds
  • Blogs: Look for RSS icons or /feed URL paths
  • Podcasts: Many podcast directories provide RSS feeds
  • Reddit: Add .rss to subreddit URLs (e.g., reddit.com/r/news/.rss)
  • YouTube: Use channel RSS feeds to track new videos
  • GitHub: Track repository releases, commits, or issues via RSS

Organizing Your Feeds

  • Create categories: Group feeds by topic (News, Tech, Sports, etc.)
  • Use tags: Add custom tags to articles for better organization
  • Smart filters: Create filters based on keywords or sources
  • Reading lists: Save important articles for later reading
  • Archive system: Develop a workflow for processing articles efficiently

Dealing with High-Volume Feeds

  • Prioritize sources: Mark favorite feeds for priority reading
  • Use filters: Automatically mark certain articles as read
  • Batch reading: Set aside time for focused reading sessions
  • Unsubscribe ruthlessly: Remove feeds that don’t provide value
  • Adjust refresh intervals: Reduce check frequency for low-priority feeds

Resources

Deploying CommaFeed on Klutch.sh provides you with a powerful, self-hosted RSS reader that puts you in control of your content consumption. With PostgreSQL database integration, automated deployments from GitHub, and persistent storage for logs, you have a production-ready setup that’s reliable and easy to maintain. The Docker-based approach ensures consistency across environments and makes updates straightforward. Whether you’re building a personal feed reader, creating a team content curation platform, or simply taking control of your news consumption, CommaFeed on Klutch.sh gives you the freedom and features you need to stay informed on your own terms.