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, SqLite or MongoDB
  • Apache Webserver (ngnix and lighttpd also possible)
selfoss supports all modern browsers, including Mozilla Firefox, Safari, Google Chrome, Opera and Internet Explorer.

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 and public/ writeable
  3. Insert database access data in config.ini
  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.

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.
  7. Insert your current database connection and your individual configuration in config.ini. Important: we change the config.ini and add new options in newer versions. You have to update the config.ini too.

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 mongodb)
db_file sqlite databasefile
db_host database hostname
db_database name of the database
db_username database username
db_password database password
db_port port for database connections
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

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 (scrolls inside the article if text length exeeds the window height)
n select next entry
shift + space select and open previous entry
k select and open previous entry (scrolls inside the article if text length exeeds the window height)
p select previous entry
s mark and unmark current selected entry
v open url of current entry in new tab/window

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

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://blog.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.

Privacy

selfoss only communicates with your private selfoss installation on your own webserver. No data will be send to anybody (just check the source code).

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!

Download

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://blog.aditu.de. The icon was created by Nadja (ArtCore), thanks for licensing it as CC. Thanks to Harald for the SqLite and MongoDB database interface.

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.