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)
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:
Configuration is optional. Any settings in config.ini will override the settings in defaults.ini. To customize settings follow these instructions:
[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
Read carefully following instructions before you update your selfoss installation:
/public/all-v*.css
and /public/all-v*.js
. Additionally, when using Lighttpd
, please check the wiki.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 |
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:
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.
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") ) ); }
Your source will have to implement a few methods. Following UML diagram shows the inheritance structure:
The class has to implement three things:
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).
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.
\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.
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.
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 (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.