Deploying Reader

Introduction

Reader (by Readeck) is a modern, self-hosted read-it-later and RSS aggregator that combines the best features of services like Pocket, Instapaper, and traditional RSS readers. Built with Go, Reader provides a fast, privacy-respecting platform for saving articles, subscribing to feeds, and organizing your reading material.

The application focuses on providing a distraction-free reading experience with clean article extraction, offline support, and powerful organization features. Reader respects your privacy by keeping all your data under your control.

Key highlights of Reader:

• Article Saving: Save any web page for later reading with clean content extraction
• RSS/Atom Feeds: Subscribe to and aggregate content from RSS and Atom feeds
• Full-Text Search: Search across all saved articles and feed content
• Tags and Categories: Organize content with flexible tagging and categorization
• Reading Progress: Track reading progress and mark articles as read
• Highlights and Notes: Annotate articles with highlights and personal notes
• Archive Mode: Permanently save complete article content offline
• Mobile-Friendly: Responsive design works great on phones and tablets
• Keyboard Navigation: Efficient keyboard shortcuts for power users
• OPML Import/Export: Easy migration from other RSS readers
• API Access: RESTful API for integration with other tools
• Open Source: Self-hosted with full data ownership

This guide walks through deploying Reader on Klutch.sh using Docker, configuring persistent storage for your reading library, and setting up the application for production use.

Why Deploy Reader on Klutch.sh

Deploying Reader on Klutch.sh provides several advantages for managing your reading:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Reader without complex orchestration. Push to GitHub, and your reading platform deploys automatically.

Persistent Storage: Attach persistent volumes for your database and saved articles. Your reading list and archives survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your reading collection from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your usage. Reader is lightweight but can handle large article collections.

Environment Variable Management: Securely store configuration through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Reader instance for convenient access.

Always-On Availability: Your reading platform runs 24/7, syncing feeds and keeping your library accessible from any device.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Reader configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) A custom domain for your Reader instance
• (Optional) OPML file from your current RSS reader for migration

Understanding Reader Architecture

Reader is built as a lean, efficient Go application:

Go Backend: A single binary handles all functionality including HTTP serving, feed fetching, and article processing.

SQLite Database: Stores all data including users, articles, feeds, and reading state in a single file for simplicity.

Article Extraction: Built-in content extraction cleans articles for distraction-free reading.

Background Workers: Feed updates and article processing happen asynchronously.

Static Assets: Compiled frontend assets are embedded in the binary for single-file deployment.

Preparing Your Repository

To deploy Reader on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

reader-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM codeberg.org/readeck/readeck:latest

# Set environment variables
ENV READECK_SERVER_HOST=0.0.0.0
ENV READECK_SERVER_PORT=8000
ENV READECK_DATA_DIR=/data

# Create data directory
RUN mkdir -p /data

# Expose the web interface port
EXPOSE 8000

# The base image includes the default entrypoint

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
READECK_SERVER_HOST	No	0.0.0.0	Server bind address
READECK_SERVER_PORT	No	8000	Server port
READECK_DATA_DIR	No	/data	Data directory path
READECK_LOG_LEVEL	No	info	Logging level (debug, info, warn, error)

Deploying Reader on Klutch.sh

Once your repository is prepared, follow these steps to deploy Reader:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Reader deployment configuration"
git remote add origin https://github.com/yourusername/reader-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. Give it a descriptive name like “reader” or “reading-list”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Reader Dockerfile.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
READECK_SERVER_HOST	0.0.0.0
READECK_SERVER_PORT	8000
READECK_DATA_DIR	/data

Attach Persistent Volumes

Add the following volume for data persistence:

Mount Path	Recommended Size	Purpose
/data	10 GB	Database, articles, and cached content

Deploy Your Application

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

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Reader container
• Provision an HTTPS certificate

Access Reader

Once deployment completes, access your Reader instance at https://your-app-name.klutch.sh. Create your account on first access.

Initial Setup and Configuration

Creating Your Account

On first access:

1. Navigate to your Reader URL
2. Create your user account with email and password
3. Configure basic preferences
4. Start adding content

Adding RSS Feeds

Subscribe to your favorite sites:

1. Click Add Feed or use the + button
2. Enter the feed URL or website URL (Reader will find the feed)
3. Optionally assign to a category
4. Configure update frequency

Importing from Other Readers

If migrating from another RSS reader:

1. Export OPML from your previous reader
2. Navigate to Settings → Import
3. Upload your OPML file
4. Review and confirm feed imports

Saving Articles

Save articles for later reading:

1. Use the bookmarklet for one-click saving
2. Share URLs directly to Reader
3. Use the browser extension if available
4. Manually add URLs through the interface

Production Best Practices

Security Recommendations

• Strong Passwords: Use complex passwords for your account
• Regular Updates: Keep Reader updated for security patches
• Access Control: Reader is single-user; secure your URL appropriately
• HTTPS Only: Klutch.sh provides this automatically

Performance Optimization

• Feed Update Intervals: Don’t refresh feeds too frequently
• Archive Management: Periodically clean old articles you won’t read
• Search Indexing: Allow time for full-text search to index new content

Backup Strategy

1. Database Backup: Back up the /data directory containing the SQLite database
2. OPML Export: Regularly export your feed list via OPML
3. Article Archive: Reader stores full article content for offline access

Troubleshooting Common Issues

Feeds Not Updating

Symptoms: Feed content is stale or not updating.

Solutions:

• Verify feed URL is accessible
• Check feed format is valid RSS/Atom
• Review logs for fetch errors
• Try removing and re-adding the feed

Articles Not Extracting Properly

Symptoms: Saved articles show incomplete or garbled content.

Solutions:

• Some sites block content extraction
• Try the original URL link
• Report extraction issues to Reader project
• Use archive feature for important articles

Search Not Finding Content

Symptoms: Articles exist but search doesn’t find them.

Solutions:

• Allow time for indexing after adding content
• Check search syntax
• Try simpler search terms
• Verify article was fully saved

Additional Resources

• Readeck Official Website
• Readeck Source Repository
• Readeck Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Reader on Klutch.sh gives you a powerful, self-hosted reading platform with automatic builds, persistent storage, and secure HTTPS access. The combination of Reader’s clean interface and Klutch.sh’s deployment simplicity means you can focus on reading rather than managing infrastructure.

With RSS aggregation, read-it-later functionality, and full-text search, Reader consolidates your reading workflow into a single, privacy-respecting application. The lightweight architecture means fast performance even on modest resources.

Whether you’re following a handful of blogs or managing hundreds of feeds alongside your saved articles, Reader on Klutch.sh provides the reliable foundation for your reading habit.