Skip to content
Klutch.sh Docs

Deploying TinyFeed

Introduction

TinyFeed is a minimalist, self-hosted RSS/Atom feed aggregator designed with simplicity in mind. Written in Go, it generates a static HTML page from your configured feeds, making it incredibly lightweight and fast. Unlike full-featured feed readers, TinyFeed focuses on doing one thing well: aggregating feeds into a clean, readable format.

The application periodically fetches your configured feeds and generates a single HTML page displaying the latest items. This static approach means minimal resource usage, fast page loads, and simple deployment without databases or complex dependencies.

Key highlights of TinyFeed:

  • Minimal Resource Usage: Single binary with no runtime dependencies
  • Static HTML Output: Generates a simple HTML page, no JavaScript required
  • Fast Performance: Written in Go for efficient feed processing
  • YAML Configuration: Simple, readable configuration format
  • Customizable Templates: Modify the output HTML with custom templates
  • Docker Support: Easy containerized deployment
  • Scheduled Updates: Configurable refresh intervals
  • Multi-Feed Support: Aggregate unlimited feeds into one view
  • No Database Required: Configuration-driven with no persistence needs
  • 100% Open Source: Available under MIT license

This guide walks through deploying TinyFeed on Klutch.sh using Docker, configuring your feeds, and customizing the output.

Why Deploy TinyFeed on Klutch.sh

Deploying TinyFeed on Klutch.sh provides several advantages:

Always-On Updates: Your feed aggregation runs continuously, keeping your feed page current without manual intervention.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your aggregated feeds.

Minimal Resource Cost: TinyFeed’s lightweight nature means low resource requirements and efficient operation.

GitHub Integration: Manage your feed configuration through version control with automatic redeployments when you update your feeds list.

Custom Domains: Serve your feed page from your own domain for a personalized experience.

No Database Management: TinyFeed’s static approach eliminates database administration overhead.

Prerequisites

Before deploying TinyFeed on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and containerization concepts
  • A list of RSS/Atom feed URLs you want to aggregate
  • (Optional) A custom domain for your feed page

Understanding TinyFeed Architecture

TinyFeed follows an extremely simple architecture:

Go Binary: A single compiled binary handles all functionality - fetching feeds, parsing content, and generating HTML.

YAML Configuration: Feeds and settings are defined in a simple YAML file.

HTML Generation: Output is a static HTML file that can be served by any web server.

Scheduled Updates: The application periodically refreshes feeds based on configured intervals.

Preparing Your Repository

Create a GitHub repository with your TinyFeed configuration.

Repository Structure

tinyfeed-deploy/
├── Dockerfile
├── feeds.yaml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/tinyfeed/tinyfeed:latest


# Set working directory
WORKDIR /app


# Copy feed configuration
COPY feeds.yaml /app/feeds.yaml


# Create output directory
RUN mkdir -p /app/output


# Set environment variables
ENV TINYFEED_CONFIG=/app/feeds.yaml
ENV TINYFEED_OUTPUT=/app/output/index.html
ENV TINYFEED_INTERVAL=30m


# Expose port for serving the static file
EXPOSE 8080


# Health check
HEALTHCHECK --interval=60s --timeout=10s --start-period=30s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1


# Start TinyFeed with built-in web server
CMD ["tinyfeed", "serve", "--config", "/app/feeds.yaml", "--port", "8080"]

Creating the Feeds Configuration

Create a feeds.yaml file with your feed subscriptions:

# TinyFeed Configuration


# Page settings
title: "My Feed Aggregator"
description: "Aggregated content from my favorite sources"


# Refresh interval (how often to fetch feeds)
interval: 30m


# Maximum items per feed
max_items: 10


# Total maximum items on the page
total_max_items: 100


# Feed sources
feeds:
  # Technology
  - name: "Hacker News"
    url: "https://news.ycombinator.com/rss"
    category: "Technology"


  - name: "Ars Technica"
    url: "https://feeds.arstechnica.com/arstechnica/index"
    category: "Technology"


  - name: "The Verge"
    url: "https://www.theverge.com/rss/index.xml"
    category: "Technology"


  # Development
  - name: "Go Blog"
    url: "https://blog.golang.org/feed.atom"
    category: "Development"


  - name: "CSS-Tricks"
    url: "https://css-tricks.com/feed/"
    category: "Development"


  # Open Source
  - name: "OpenSource.com"
    url: "https://opensource.com/feed"
    category: "Open Source"


  # Custom Blogs
  - name: "My Favorite Blog"
    url: "https://example.com/feed.xml"
    category: "Blogs"

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
output/

Deploying TinyFeed on Klutch.sh

Follow these steps to deploy your TinyFeed instance:

    Push Your Repository to GitHub

    Initialize and push your repository:

    Terminal window
    git init
    git add Dockerfile feeds.yaml .dockerignore README.md
    git commit -m "Initial TinyFeed configuration"
    git remote add origin https://github.com/yourusername/tinyfeed-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Name it something like “feeds” or “tinyfeed”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your TinyFeed repository.

    Configure HTTP Traffic

    TinyFeed serves a static HTML page. In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 8080

    Set Environment Variables

    Configure optional environment variables:

    VariableValue
    TINYFEED_INTERVAL30m
    TZAmerica/New_York (your timezone)

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Build your Docker image
    • Start the TinyFeed service
    • Provision an HTTPS certificate

    Access Your Feed Page

    Navigate to https://your-app-name.klutch.sh to view your aggregated feeds.

Configuring Feeds

Adding Feeds

Add new feeds to your feeds.yaml:

feeds:
  - name: "New Source"
    url: "https://example.com/feed.xml"
    category: "General"

Push the changes to trigger a redeployment.

Organizing by Category

Group feeds by category for organized display:

feeds:
  # Technology News
  - name: "TechCrunch"
    url: "https://techcrunch.com/feed/"
    category: "Tech News"


  - name: "Wired"
    url: "https://www.wired.com/feed/rss"
    category: "Tech News"


  # Security
  - name: "Krebs on Security"
    url: "https://krebsonsecurity.com/feed/"
    category: "Security"


  - name: "Schneier on Security"
    url: "https://www.schneier.com/feed/"
    category: "Security"

Limiting Items

Control how many items display from each feed:

# Per-feed limit
max_items: 5


# Total page limit
total_max_items: 50
SourceFeed URL
Hacker Newshttps://news.ycombinator.com/rss
Reddit (subreddit)https://www.reddit.com/r/programming/.rss
GitHub Trendinghttps://rsshub.app/github/trending/daily
Lobstershttps://lobste.rs/rss
Dev.tohttps://dev.to/feed

Customizing the Output

Custom Templates

Create a custom HTML template for your feed page:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ .Title }}</title>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
            background: #f5f5f5;
        }
        .item {
            background: white;
            padding: 15px;
            margin-bottom: 10px;
            border-radius: 5px;
            box-shadow: 0 1px 3px rgba(0,0,0,0.1);
        }
        .item a {
            color: #0066cc;
            text-decoration: none;
        }
        .item a:hover {
            text-decoration: underline;
        }
        .meta {
            color: #666;
            font-size: 0.9em;
        }
        .category {
            display: inline-block;
            background: #e0e0e0;
            padding: 2px 8px;
            border-radius: 3px;
            font-size: 0.8em;
        }
    </style>
</head>
<body>
    <h1>{{ .Title }}</h1>
    <p>{{ .Description }}</p>
    <p class="meta">Last updated: {{ .UpdatedAt }}</p>


    {{ range .Items }}
    <div class="item">
        <a href="{{ .Link }}" target="_blank">{{ .Title }}</a>
        <div class="meta">
            <span class="category">{{ .Category }}</span>
            {{ .Source }} - {{ .PublishedAt }}
        </div>
    </div>
    {{ end }}
</body>
</html>

Styling Options

Modify CSS in your template for different looks:

  • Dark mode: Adjust background and text colors
  • Mobile-friendly: Template includes viewport meta tag
  • Print-friendly: Add print media queries

Update Intervals

Configuring Refresh Rate

Adjust how often feeds are fetched:

# In feeds.yaml
interval: 15m  # Every 15 minutes


# Or via environment variable
ENV TINYFEED_INTERVAL=1h  # Every hour
Use CaseInterval
News aggregation15-30 minutes
Blog reading1-2 hours
Low-traffic feeds6-12 hours

Performance Considerations

Resource Usage

TinyFeed is extremely lightweight:

MetricTypical Value
Memory20-50 MB
CPUMinimal (spikes during fetch)
Storage< 10 MB

Optimizing Feed Count

For best performance:

  • Limit to 20-30 feeds for quick refreshes
  • Remove feeds that update infrequently
  • Use category limits to control output size

Monitoring

Checking Status

Monitor your TinyFeed deployment through:

  1. Klutch.sh Dashboard: View runtime status and logs
  2. Page Updates: Check the “Last updated” timestamp on the page
  3. Health Endpoint: Access /health if configured

Viewing Logs

TinyFeed logs include:

  • Feed fetch status
  • Parse errors
  • Generation timing

Troubleshooting Common Issues

Feeds Not Updating

Symptoms: Page shows old content.

Solutions:

  • Check that feed URLs are accessible
  • Verify interval setting is reasonable
  • Look for fetch errors in logs
  • Ensure container is running

Feed Parse Errors

Symptoms: Specific feeds not appearing.

Solutions:

  • Validate feed URL returns valid RSS/Atom
  • Check for authentication requirements
  • Some feeds may block certain user agents

Page Not Loading

Symptoms: 502 or connection errors.

Solutions:

  • Verify container is running in dashboard
  • Check port configuration is 8080
  • Review startup logs for errors

Slow Page Generation

Symptoms: Long wait times for page loads.

Solutions:

  • Reduce number of feeds
  • Lower max_items per feed
  • Increase interval between refreshes

Updating TinyFeed

To update to a newer version:

  1. Update the image tag in your Dockerfile: 
    FROM ghcr.io/tinyfeed/tinyfeed:v1.2.0
  2. Push changes to trigger redeployment

Alternative Configurations

Read-Only Mode

Generate static files for external hosting:

CMD ["tinyfeed", "generate", "--config", "/app/feeds.yaml", "--output", "/app/output/"]

JSON Output

Export feeds as JSON for custom frontends:

output_format: json

Additional Resources

Conclusion

TinyFeed on Klutch.sh offers a refreshingly simple approach to feed aggregation. Instead of complex feed readers with databases, accounts, and countless features, TinyFeed delivers exactly what many users want: a clean page showing the latest from their favorite sources.

The static HTML approach means fast page loads, minimal resource usage, and straightforward deployment. Combined with Klutch.sh’s automatic HTTPS and GitHub integration, you get an always-updated feed page with minimal effort.

Whether you’re curating news sources for personal reading, creating a topic-specific aggregator to share with others, or building a simple news portal, TinyFeed provides the foundation without the overhead of more complex solutions.