Documentation

Requirements

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.

Installation

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

Configuration

Configuration is optional. Any settings in config.ini will override the settings in defaults.ini. To customize settings follow these instructions: Copy defaults.ini to config.ini. Edit config.ini and delete any lines you do not wish to override. 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: Backup your database and your "data" folder IMPORTANT: don't delete the "data" folder. Delete all old files and folders excluding the folder "data". Upload all new files and folders excluding the data folder (IMPORTANT: also upload the invisible .htaccess files). Rename your folder /data/icons into /data/favicons 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. Clean your browser cache. For further questions or on any problem use our 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 https://yourselfossurl.com/opml and upload it there.

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_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. https://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 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=https://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. 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

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 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: <?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: The class has to implement three things: A load($params) function will be executed by selfoss when the content will be updated (the https://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).

function will be executed by selfoss when the content will be updated (the https://your-selfoss-url.com/update will be executed). This function has one parameter 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 ). 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.

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