Screenshots

Documentation

Requirements

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

  • PHP 5.3 or higher
  • MySQL, PostgreSQL or Sqlite
  • Apache Webserver (ngnix and lighttpd also possible)

Ensure that you have 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.

Installation

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 http://yoururl.com/update via wget or curl. You can also execute the update.php from commandline.
For further questions or on any problem use our support forum.

Configuration

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:

                    
[globals]
username=secretagent
password=5d95c032abce4865d49ee225d28a8a939ea39a924a158f0056ebb1880d9
salt=1291929@9394$95%939201098*61234324(@#$(!*@#981923123
                

Sample config.ini file with a MySQL database connection:

                    
[globals]
db_type=mysql
db_host=localhost
db_database=selfoss
db_username=secretagent
db_password=life0fD4ng3r
db_port=3306
                

Update

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. Delete the files /public/all.css and /public/all.js
  6. Clean your browser cache.
For further questions or on any problem use our support forum.

Import your feeds from Google Reader (OPML File)

Visit the page http://yoururl.com/opml for importing your OPML File. If you are a user of the google reader then use http://www.google.com/reader/subscriptions/export or https://www.google.com/takeout/ to get all your feeds in one opml file.

Configuration

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_level set logging level; the log file will be found on /data/logs/default.logfollowing logging levels are available: DEBUG, INFO, NOTICE, WARNING, ERROR, NONE 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
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. http://your_selfoss_url.com/password
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 writeprotected 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 prefered homepage. Choose between newest, unread and starred. Default = newest.
auto_mark_as_read set this to 1 for automatically marking items as read after open/read them.
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=http://anonym.to/?
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.
readability default API key for all feeds fetched by readability spout. You can also enter the readability API key in the spout parameters for every single feed.
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, r = readability, 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
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

Shortcuts

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

Extend

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
  • RSS Feeds with readability

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).

A german speaking tutorial on how to add own data sources can be found on http://www.aditu.de. 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:

        <?PHP
        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")
                )
            );
        }
                

Methods

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 http://your-selfoss-url.com/update 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 php.net 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).

Thumbnails

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 tobias.zeising@aditu.de.

API

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.

License

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!

About

selfoss is a project of Tobias Zeising (tobias.zeising@aditu.de).

More information about selfoss can be found on my german speaking blog http://www.aditu.de. 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 fancyapps.com.