Deploying Selfoss

Introduction

Selfoss is a lightweight, multi-purpose RSS reader, live stream aggregator, and mashup application. It collects content from various sources including RSS feeds, Twitter, Reddit, and other social networks, presenting everything in a clean, responsive web interface that works beautifully on both desktop and mobile devices.

Built with PHP and designed for simplicity, Selfoss focuses on providing a fast, distraction-free reading experience. The application supports multiple users, keyboard shortcuts, and integrates with various read-later services like Pocket and Wallabag.

Key highlights of Selfoss:

Multi-Source Aggregation: Collect from RSS, Atom, Twitter, Reddit, and more
Responsive Design: Mobile-friendly interface that adapts to any screen size
Keyboard Navigation: Efficient keyboard shortcuts for power users
Tagging System: Organize sources with tags for filtered views
Read-Later Integration: Send articles to Pocket, Wallabag, or other services
OPML Import/Export: Easy migration from other RSS readers
RESTful API: Build custom clients or integrate with other tools
Multiple Database Support: SQLite, MySQL, or PostgreSQL
Lightweight: Minimal server requirements
100% Open Source: Licensed under GPL-3.0

This guide walks through deploying Selfoss on Klutch.sh using Docker, configuring feed sources, and setting up your personalized news aggregator.

Why Deploy Selfoss on Klutch.sh

Deploying Selfoss on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds your Selfoss configuration without complex PHP/web server setup.

Persistent Storage: Attach persistent volumes for your database and configuration that survive restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure feed reading.

Always-On Updates: Your feed aggregator continuously updates in the background 24/7.

Custom Domains: Use your own domain for a personalized reading experience.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Selfoss configuration
Basic familiarity with Docker and containerization concepts
A list of RSS/Atom feeds you want to follow

Preparing Your Repository

Create a GitHub repository with your Selfoss configuration.

Repository Structure

selfoss-deploy/
├── Dockerfile
├── config.ini
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM hardware/selfoss:latest

# Copy custom configuration
COPY config.ini /selfoss/config.ini

# Set proper permissions
RUN chown -R nginx:nginx /selfoss

# Expose the web interface port
EXPOSE 8888

Creating the Configuration File

Create a config.ini file:

[globals]
; Database configuration
db_type=sqlite
db_file=data/selfoss.db

; Authentication
username=admin
password=

; Base URL (set via environment variable)
base_url=

; Auto-mark as read
auto_mark_as_read=1

; Items per page
items_perpage=50

; Update interval (minutes)
auto_update=1

; Homepage type (unread, newest, starred)
homepage=unread

; Anonymizer for links
anonymizer=

; Allow public access without login
public=0

; Share buttons
share=gtpf

Environment Variables Reference

Variable	Required	Default	Description
`SELFOSS_USERNAME`	No	-	Admin username
`SELFOSS_PASSWORD`	No	-	Admin password (hashed)
`SELFOSS_DB_TYPE`	No	sqlite	Database type: sqlite, mysql, pgsql
`SELFOSS_DB_HOST`	No	-	Database host for MySQL/PostgreSQL
`SELFOSS_DB_NAME`	No	-	Database name
`SELFOSS_DB_USER`	No	-	Database username
`SELFOSS_DB_PASS`	No	-	Database password
`CRON_PERIOD`	No	15m	Feed update interval

Deploying Selfoss on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile config.ini .dockerignore
git commit -m "Initial Selfoss deployment configuration"
git remote add origin https://github.com/yourusername/selfoss-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 with a descriptive name like “selfoss” or “rss-reader”.

Create a New App

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

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8888

Set Environment Variables

Add optional environment variables:

Variable	Value
`CRON_PERIOD`	`15m`

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
`/selfoss/data`	5 GB	SQLite database, favicons, and thumbnails

Deploy Your Application

Click Deploy to start the build process.

Access Selfoss

Once deployment completes, access your Selfoss instance at https://your-app-name.klutch.sh.

Initial Configuration

Setting Up Authentication

Access your Selfoss instance
Navigate to Settings
Create your admin username and password
Save the configuration

Adding Feed Sources

Click the + button or go to Sources
Enter the feed URL
Select tags for organization
Configure source-specific settings
Click Save

Importing OPML

Export OPML from your previous RSS reader
Go to Settings > Import
Upload your OPML file
Feeds are automatically added with tags preserved

Using Selfoss

Keyboard Shortcuts

Key	Action
`j`	Next item
`k`	Previous item
`s`	Star/unstar item
`m`	Mark as read/unread
`o`	Open original article
`v`	Open in new tab
`r`	Reload
`t`	Tag filter

Filtering Content

Click tags in the sidebar to filter by source category
Use the search bar to find specific articles
Toggle between unread, starred, and all items

Selfoss supports sharing to:

Twitter (now X)
Facebook
Pocket
Wallabag
Email

Configure sharing options in the settings.

Troubleshooting

Feeds Not Updating

Symptoms: New articles don’t appear.

Solutions:

Check the cron job is running (view logs)
Verify feed URLs are accessible
Check for feed parsing errors in the source settings

Symptoms: Cannot log in to the admin interface.