selfoss is not a hosted service. It has to be installed on your own webserver. This webserver must fulfil the following requirements (which are available from most providers)

  • PHP 5.4 or higher with the php-gd and php-http extensions enabled. Some spouts may also require curl or mbstring extensions.
  • MySQL 5.5.3 or higher, PostgreSQL, or Sqlite
  • Apache Webserver (nginx and lighttpd also possible)

Ensure that you have mod_authz_core, mod_rewrite and mod_headers enabled.

selfoss supports all modern browsers, including Mozilla Firefox, Safari, Google Chrome, Opera and Internet Explorer. selfoss also supports mobile browsers on iPad, iPhone, Android and other devices.


selfoss is a lightweight php based application. Just follow the simple installation instructions:

  1. Upload all files of this folder (IMPORTANT: also upload the invisible .htaccess files)
  2. Make the directories data/cache, data/favicons, data/logs, data/thumbnails, data/sqlite and public/ writeable
  3. Insert database access data in config.ini (see below — you have not to change anything if you would like to use sqlite)
  4. You don't have to install the database, it will be created automatically
  5. Create cronjob for updating feeds and point it to via wget or curl. You can also execute the cliupdate.php from commandline.
For further questions or any problems, use our support forum. For a more detailed step-by-step example installation, please visit the wiki.


Configuration is optional. Any settings in config.ini will override the settings in defaults.ini. To customize settings follow these instructions:

  1. Copy defaults.ini to config.ini.
  2. Edit config.ini and delete any lines you do not wish to override.
  3. Do not delete the [globals] line.

Sample config.ini file which provides password protection:


Sample config.ini file with a MySQL database connection:



Read carefully following instructions before you update your selfoss installation:

  1. Backup your database and your "data" folder
  2. IMPORTANT: don't delete the "data" folder. Delete all old files and folders excluding the folder "data".
  3. Upload all new files and folders excluding the data folder (IMPORTANT: also upload the invisible .htaccess files).
  4. Rename your folder /data/icons into /data/favicons
  5. If upgrading from 2.17 or earlier, delete the files /public/all-v*.css and /public/all-v*.js. Additionally, when using Lighttpd, please check the wiki.
  6. Clean your browser cache.
For further questions or on any problem use our support forum.

Import your feeds from a different RSS reader

Selfoss supports importing OPML files. Find the OPML export in the old application, it is usually located somewhere in settings. Then visit the page and upload it there.


selfoss offers the following configuration parameters. You can set the config parameters in the config.ini file.

Parameter Functionality
db_type database type (sqlite, mysql or pgsql)
db_file sqlite databasefile
db_host database hostname
db_database name of the database
db_username database username
db_password database password
db_prefix table prefix for MySQL/SQLite databases
db_port port for database connections (3306 for mysql, 5432 for PostgreSQL
logger_destination By default, the logs are saved to data/logs/default.log but you can choose a different file by specifying a file path prefixed by file:. Setting file:php://stderr is especially useful when running selfoss on a PaaS or inside Docker. Alternately, you can set the option to error_log to redirect the messages to SAPI error log – handy for PHP-FPM, which discards stderr by default.
logger_level set logging level – following logging levels are available: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG. Additionally, you can use NONE pseudo-level to turn the logging off completely.
Use this for troubleshooting on updating feeds (but be aware that the log file can become very large.)
items_perpage number of entries per page on your stream
items_lifetime days until items will be deleted (marked items will never be deleted)
base_url base url of the selfoss page; use this option if you use a ssl proxy which changes the $_SERVER globals, most notably the URL path in which the app is installed.
username username for optional login. Just set username and password for enabling login.
password password hash for optional login. You can generate a password hash by using following page of your selfoss installation.
salt salt for hashing the password (see Wikipedia)
public if you use login (username and password is set), you can allow guests to see your stream. Enter 1 for enabling this write-protected mode
rss_title title of the generated rss feed
rss_max_items maximum amount of items in the generated rss feed
rss_mark_as_read set this to 1 for automatically marking items as read after you fetched them via rss
homepage set here your preferred homepage. Choose between newest, unread and starred. It is also possible to configure a tag (e.g. unread/tag-yourtag) or a source (e.g. newest/source-123). Default = newest.
auto_mark_as_read set this to 1 for automatically marking items as read after open/read them.
auto_collapse set this to 1 for automatically collapsing items when another one is opened.
auto_stream_more set this to 0 to disable autoloading of more items when you scroll down. With 1, a click on a button is required instead.
language set 0 or leave empty for auto detection (browser language) or set "de" for German, "en" for English, "fr" for French, "cs" for Czech, "nl" for Dutch, "ru" for Russian, "tr" for Turkish, "lv" for Latvian, "tw" for Traditional Chinese, "cn" for Simplified Chinese
anonymizer set here your anonymizer service url. e.g.: anonymizer=
use_system_font set use_system_font=1 if you have problems with special characters. Then instead of Open Sans the font Arial will be used.
allow_public_update_access set allow_public_update_access=1 for allowing public access for /update (anybody can access and start the update job).
share share defines which share buttons beneath the entry are visible. Default is share=gtfprde (g = google, f = facebook, t = twitter, p = pocket, d = delicious, w = wallabag, e = email). When you would like to show only facebook and twitter share button use share=ft.
wallabag wallabag url. url to wallabag homepage
wallabag_version set this to 1 or 2 depending on your wallabag version (1 for version 1.x or 2 for version 2.x)
unread_order set unread_order=asc to read your unread items from the oldest to the newest, leave it empty or to desc to read from the newest to the oldest
load_images_on_mobile set load_images_on_mobile=1 for allowing image lazy loading on mobile devices
auto_hide_read_on_mobile hide read articles on mobile devices
scroll_to_article_header scrolls to the article header after selecting an article (enabled by default)
env_prefix only consider ENV variables that start with this prefix as additional config variables. Defaults to "SELFOSS_".
camo_domain Camo domain used to proxify images (optional). See atmos/camo for more details
camo_key Camo domain used to proxify images (optional). See atmos/camo for more details


selfoss offers some keyboard shortcuts. They are very similar to the google reader shortcuts.

Shortcut Functionality
space select and open next entry
j select and open next entry
n select next entry
select next entry (and open it when the current is open)
shift + space select and open previous entry
k select and open previous entry
p select previous entry
select previous entry (and open it when the current is open)
s mark and unmark current selected entry as starred/unstarred
m mark and unmark current selected entry as read/unread
t throw current item (mark as read and open next)
shift + t throw current item (mark as read and open previous)
v open url of current entry in new tab/window
Shift + v open url of current entry in new tab/window and mark read
Ctrl + m mark all as read
r reload the list
o open / close current item
shift + o close all open items
shift + n open newest items page
shift + u open unread items page
shift + s open starred items page


You can easily add your own data sources. Spouts (aka plugins) fetch the content from the different sources. Some spouts are included:

  • RSS Feeds
  • Images from a RSS Feed
  • Images from deviantArt Users
  • Images from tumblr
  • Your twitter timeline
  • Tweets of a twitter user
  • heise News with full content
  • golem News with full content
  • MMOSpy News with full content

If you want to get the newest entries from your own source (e.g. an IMAP Email Account, Log Files or any data from your own application), you can include a new spout in your selfoss stream by writing just one php class (saved in one php file).

Create a new php file under /spouts/your_spouts/your_spout.php (choose a name for your_spouts and your_spout). The easiest way is to copy the /spouts/rss/feed.php and to modify this file.

Member Variables

Set the $name and $description variable with the name and description of your spout. The $params contain the definition of the input fields which a user will have to fill to add a new source of your spout (e.g. username and password for accessing the source data).

A simple example for the member variables of a spout for accessing an IMAP email account:

        namespace spouts\mail;
        class imap extends \spouts\spout {
            public $name = 'Email';
            public $description = 'email imap account as source';
            public $params = array(
                    "email" => array(
                    "title"      => "Email",
                    "type"       => "text",
                    "default"    => "",
                    "required"   => true,
                    "validation" => array("email")
                "password" => array(
                    "title"      => "Password",
                    "type"       => "password",
                    "default"    => "",
                    "required"   => true,
                    "validation" => array("notempty")
                "host" => array(
                    "title"      => "URL",
                    "type"       => "text",
                    "default"    => "",
                    "required"   => true,
                    "validation" => array("notempty")


Your source will have to implement a few methods. Following UML diagram shows the inheritance structure:

selfoss source uml diagramm

The class has to implement three things:

  • A load($params) function will be executed by selfoss when the content will be updated (the will be executed). This load function has one parameter $params which contains the user defined parameters (e.g. username, password or anything which the user has configured (as you can define in the members variable $params). This function contains your source code for fetching the data (e.g. loading the emails from an IMAP email account).
  • You have to implement the Iterable interface. selfoss will use it to iterate over all single entries of your source (e.g. the emails which were fetched by the load function). See manual (OOP5 iterators) for more informations about this iterator functions.
  • selfoss iterates over all the entries by using the iterable interface. selfoss will receive all information about the entries by using the functions defined by the abstract class \spouts\spout (e.g. it will get the email subject by executing the getTitle() method).


If you would like to show thumbnails instead of text, you have to implement the optional method getThumbnail(). This method have to return the url of the image. selfoss will load and generate the thumbnail automatically. See \spouts\rss\images.php for an example. This spout searches for an image in an rss feed and returns it.

Your Spouts

Feel free to send us your own spouts. We are really happy about new sources we can add to further versions of selfoss. You can send them by email to


selfoss offers a restful JSON API for accessing or changing all selfoss data. Just use this API for your selfoss App or any other programm or plugin. Visit this github wiki page for a detailed API documentation.


selfoss is licensed under the GPLv3 license.

You are allowed to use, modifiy or study this program completely for free. If you need any other licence than GPLv3 then feel free to contact me!


selfoss is a project of Tobias Zeising (

More information about selfoss can be found on my german speaking blog The icon was created by Nadja (ArtCore), thanks for licensing it as CC.

Selfoss is named by the wonderfull waterfall in Iceland (see Wikipedia). Many single waterfalls converge to produce one big fall. This seems to be a good metaphor for the many sources from the web which will be shown in one stream.

FancyBox on this page is from