Unnikked - Esperienze personali in campo informatico

Selfoss – aggregatore di flussi per tenersi aggiornati

In questo articolo tratterò finalmente uno dei miei progetti preferiti open source self hosted: selfoss.

Selfoss è un aggregatore di flussi (stream) di vario genere: feed rss, timeline di twitter e facebook, tumblr, reddit ecc.

E’ ormai da quasi un anno che uso questa piattaforma e finalmente ho deciso di recensirla.

Le caratteristiche principali di questa applicazione sono:

  • Accesso tramite interfaccia grafica dal web
  • E’ un aggregatore universale
  • Open source e gratuito
  • Facilmente estensibile per far riconoscere nuove tipologie di flussi
  • Supporto mobile: Android, iOS etc
  • Applicazione scritta in PHP che pesa poco: circa 2MB
  • Supporta MySQL, SQLite e Postgre SQL
  • Importazione di contenuti esterni tramite il formato OPML
  • Api REST per l’integrazione con servizi esterni

Interfaccia grafica

Selfoss dispone di una accattivante interfaccia grafica dal facile utilizzo, si adatta automaticamente in base alle dimensioni dello schermo.

Desktop

Selfoss - Desktop

Tablet

Selfoss - Tablet

Smartphone

Selfoss - Smartphone

L’applicazione mostra tutti i flussi raccolti in tre macro categorie:

  • Non Lette – qui selfoss mostra tutte le nuovi voci presenti nel database
  • Recenti – qui selfoss mostra tutte le voci lette di recente
  • Contrassegnate – qui selfoss mostra tutte le voci contrassegnate

Sono presenti due sezioni con cui è possibile filtrare il flusso e leggere le voci assegnati ad un specifico tag o flusso:

  • Parole Chiave – da qui è possibile filtrare il flusso principale tramite le parole chiavi (tag) assegnate ai flussi
  • Fonti – da qui è possibile scegliere il flusso specifico da mostrare ### Lettura di una voce

Cliccando su una voce mostrata comparirà il relativo contenuto in linea con l’interfaccia grafica.

Selfoss - lettura voce

  • Contassegna – permette di salvare permanentemente un articolo letto
  • Segna come letta – permette di segnare l’elemento come letto
  • Apri – apre il link originario del contenuto
  • Interazioni social – permette di condividere i contenuti tramite i canali social

Scorciatoie da tastiera

E’ possibile interagire con l’applicazione tramite shortcut per rendere più produttivo la visione delle voci.

Scorciatoria Funzionalità
space seleziona ed apre la prossima voce
j seleziona ed apre la prossima voce
n selezione la prossima voce
selezione la prossima voce (e la apre quando la voce corrente è aperta)
shift + space seleziona ed apre la precedente voce
k seleziona ed apre la precedente voce
p selezione la precedente voce
selezione la precedente voce
s contrassegna o toglie il contrassegno alla voce selezionata
m contrassegna la voce selezionata come letta/non letta
t ignora la voce corrente (contrassegna come letta e apre la prossima)
shift + t ignora la voce corrente (contrassegna come letta e apre la precedente)
v apre il collegamento della voce corrente in un nuovo tab/finestra del browser
Shift + v apre il collegamento della voce corrente in un nuovo tab/finestra del browser e la contrassegna come letta
Ctrl + m tutte le voci come lette
r ricarica la lista
o apre / chiude la voce corrente
shift + o chiude tutte le voci aperte
shift + n apre la sezione Recenti
shift + u apre la sezione Non lette
shift + s apre la sezione Contrassegnate

Aggiunta di un nuovo flusso

Tramite l’icona a forma di nuvola è possibile gestire ed inserire o importare flussi.

Selfoss - aggiunta fonte

E’ possibile aggiungere diverse fonti come mostrato in figura, ogni fonte avrà dei parametri di configurazioni specifici.

Selfoss - spouts

Il campo Titolo serve per specificare il titolo della fonte e il campo Parole chiave serve per associate tale flusso ad una etichetta specifica.

Tramite il sistema di plugin è possibile aggiungere nuovi controllori (spouts) per gestire nuovi flussi di dati, tale caratteristica è, secondo me, ciò che rende selfoss molto versatile rispetto ai tradizionali lettori feed RSS.

Installazione

Requisiti

Innanzitutto assicuriamoci di disporre di un ambiente LAMP sul server evetualmente associarlo ad un virtual host specifico e assicuriamoci che le dipendenze dell’applicazione siano soddisfatte:

  • PHP 5.3+
  • MySQL, PostgreSLQ o SQLite
  • Apache, Nginx o lighthttpd

Se viene utilizzato Apache assicuriamoci che mod_rewrite e mod_headers siano abilitate.

Download pacchetto e installazione

E possibile installare le ultime modifiche apportate all’applicazione clonando la repository oppure scaricando l’ultima versione disponibile.

Dopo aver scaricato o clonato la repository sul server assicuriamoci che le cartelle ata/cache, data/favicons, data/logs, data/thumbnails, data/sqlite e public/ abbiano i permessi in scrittura.

Se installato su un VPS è sufficiente ripristinare la proprietà dell’utente www-data:

sudo chown -R www-data:www-data /percorso/selfoss

E impostiamo i permessi su 755:

sudo chmod -R 755 /percorso/selfoss

Inseriamo ora i dettagli del database nel file config.ini (se non si vuole usare MySQL non è necessario specificare alcun database, il sistema utilizzerà di default SQLite, bisogna averlo installato sul server).

Il database in ogni caso verrà creato automaticamente.

E’ consigliato creare un cronjob che faccia eseguire periodicamente il file update.php per permettere a selfoss di catturare nuove voci dai flussi indicati.

E’ ora possibile aprire l’applicazione all’indirizzo configurato.

File di configurazione

La configurazione è opzionale. Qualsiasi modifica al file config.ini sovrascrive le impostazioni in defaults.ini. Per personalizzare le impostazioni è necessario seguire queste istruzioni:

  • Copia defaults.ini su config.ini.
  • Modifica config.ini ed elimina i parametri che non si vogliono sovrascrivere
  • Non eliminare la linea [globals]

Ecco un esempio di configurazione del file config.ini che fornisce la protezione tramite password (di default l’accesso è pubblico!)

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

Invece ecco un esempio per utilizzare MySQL come database.

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

Ecco la tabella dei parametri che è possibile personalizzare:

Parametro Funzionalità
db_type di database (sqlite, mysql o pgsql)
db_file sqlite file di database
db_host database hostname
db_database nome del database
db_username database username
db_password database password
db_prefix prefisso tabella per MySQL/SQLite
db_port porta per la connessione al database (3306 per mysql, 5432 per PostgreSQL)
logger_level livello di log; il file di log si trova /data/logs/default.log sono disponibili i seguenti livelli: DEBUG, INFO, NOTICE, WARNING, ERROR, NONE usalo per la risoluzione di problemi durante l’aggiornamenti dei feed (ma presta attenzione che il file di log potrebbe diventare molto grande)
items_perpage numero di voci per pagina nel flusso principale
items_lifetime i giorni per la quale una voce è mantenuta del database (le voci contrassegnate non verranno eliminate)
base_url indirizzo di base della pagina di selfoss; usa questa opzione se usi un proxy ssl poiché cambia la variabile globale $_SERVER
username username per accesso opzionale. Imposta un username e una password per abilitare il login.
password hash della password per il login opzionale. Puoi generare un hash per la password usando questa pagina dell’installazione di selfoss http://your_selfoss_url.com/password
salt salt per l’hashing della password (vedi Wikipedia)
public se usi l’accesso (username e password sono impostati), puoi permettere agli ospiti di vedere il flusso principale. Inserisci 1 per abilitare questa modalità di scrittura protetta
rss_title titolo del feed rss generato.
rss_max_items numero massimo di elementi nel feed rss generato
rss_mark_as_read impostalo ad 1 per contrassegnare automaticamente le voci come lette dopo averle ottenute tramite rss
homepage imposta il flusso preferito in homepage tra newest, unread e starred. Default = newest.
auto_mark_as_read imposta a 1 per contrassegnare automaticamente le voci come lette dopo averle aperte/lette.
auto_stream_more imposta a per disabilitare il caricamento automatico delle altre voci mentre si scorre in basso la pagina. Con 1 è richiesto un click sul pulsante.
language lascia a o vuoto per scoprire automaticamente la lingua (del browser) o imposta a “de” per il tedesco, “en” per l’inglese, “fr” per il francese, “cs” per il ceco, “nl” per l’olandese, “ru” per il russo, “tr” per il turco, “lv” per il lituato e “cn” per il cinese semplificato
anonymizer imposta qui il servizio di anonimazione url. es: anonymizer=http://anonym.to/?
use_system_font imposta a 1 se si hanno problemi con i caratteri spaciali, verrà usato Arial invece di Open Sans.
readability chiave api di default per tutti i feed catturati dallo spout readability. Puoi anche inserire la chiave api di readability nei parametri dello spout per ogni singolo feed.
allow_public_update_access imposta a 1 per permettere l’accesso pubblico a /update (tutti possono accedere e avviare il processo di aggiornamento)
share definisce quali pulsanti di condivisone sono visibili sotto ogni voce. Default è gtfprde (g = google, f = facebook, t = twitter, p = pocket, r = readability, d = delicious, w = wallabag, e = email). Se vuoi abilitare solo facebook e twitter usa share=ft
wallabag url a wallabag
unread_order imposta a asc per leggere le voci dalla più vecchia alla più recente, lasciala vuota per leggere dalla più recente alla più vecchia
load_images_on_mobile imposta a 1 per permettere il caricamento dinamico delle immagini sui dispositivi mobili

Aggiornamento

Per aggiornare una installazione di selfoss basta seguire questi passaggi

  • Effettua un backup del database e della cartella "data".
  • IMPORTANTE: non eliminare la cartella “data”. Elimina tutti i vecchi file e cartelle escludendo solo la cartella “data”.<liCarica tutti i file e le cartelle esclusa la cartella “data” (IMPORTANTE: carica anche il file invisibile .htaccess)</li>

  • Rinomina la cartella /data/icons in /data/favicons
  • Cancella i file /public/all.css e /public/all.js
  • Cancella la cache del browser

Scrivere le proprie estensioni

Selfoss mette a disposizione un mini framework per l’implementazione di nuovi plugin, chiamati spouts, per l’integrazione di nuovi flussi di informazioni (email, file di log ecc).

L’architettura del sistema dei plugin è descritta schematicamente dal seguente diagramma UML:

Selfoss - uml

Bisogna creare una classe php e inserirla nella cartella /spouts/il_tuo_spout/tuo_spout.php.

Variabili interne

Le variabili $name e $description contengono il nome e la descrizione dello spout. La variabile $params contiene la definizione dei parametri dei campi di ingresso mostrati all’utente che deve compilare. Ecco un esempio per un ipotetico spout per leggere le email:

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

Metodi

La classe deve implementare tre cose:

  • La funzione load($params) che sarà eseguita da selfoss quando i contenuti saranno aggiornati (quando viene eseguito update.php). La funzione load ha un solo parametro che l’utente ha configurato. Questa funzione contiene il codice sorgente per catturare i dati (es. caricare le email dall’account IMAP)
  • Bisogna implementare l’interfaccia Iterable. Selfoss la userà in seguito per iterare su ogni singola voce della sorgente (es. le email scaricate dalla funzione load)
  • Selfoss itera su tutte le voci usando l’interfaccia Iterable. Selfoss riceverà tutte le informazioni sulle voci usando le funzioni definite dalla classe astratta \spouts\spout (es. riceverà il soggetto della email eseguendo il metodo getTitle())

Ecco un esempio di spout che ho implementato: permette di leggere tutti i tweet presenti in una lista di Twitter, per semplicità ho ereditato l’implementazione dello spout usertimeline e ho modificato solo le funzionalità necessarie.

<?php

namespace spouts\twitter;

class listtimeline extends \spouts\twitter\usertimeline {
	public function __construct() {
		$this->name = 'Twitter - List timeline';
		$this->description = 'The timeline of a given list';
		$this->params = array(
	        "consumer_key" => array(
	            "title"      => "Consumer Key",
	            "type"       => "text",
	            "default"    => "",
	            "required"   => true,
	            "validation" => array("notempty")
	        ),
	        "consumer_secret" => array(
	            "title"      => "Consumer Secret",
	            "type"       => "password",
	            "default"    => "",
	            "required"   => true,
	            "validation" => array("notempty")
	        ),
	        "slug" => array(
	            "title"      => "List Slug",
	            "type"       => "text",
	            "default"    => "",
	            "required"   => true,
	            "validation" => array("notempty")
	        ),
	        "owner_screen_name" => array(
	            "title"      => "Username",
	            "type"       => "text",
	            "default"    => "",
	            "required"   => true,
	            "validation" => array("notempty")
	        )
	    );
	}

  public function load($params) {
        $twitter = new \TwitterOAuth($params['consumer_key'], $params['consumer_secret']);
        $timeline = $twitter->get('lists/statuses', array('slug' => $params['slug'], 'owner_screen_name' => $params['owner_screen_name'], 'include_rts' => 1, 'count' => 50));
        if(isset($timeline->error))
            throw new \exception($timeline->error);
        
        if(!is_array($timeline))
            throw new \exception('invalid twitter response');
        
        $this->items = $timeline;
        
        $this->htmlUrl = 'http://twitter.com/' . urlencode($params['owner_screen_name']);
    }

}

Api Rest

Selfoss dispone anche di un insieme di API che segue la filosofia REST per poter permettere di accedere tramite applicazioni esterne alla piattaforma, qui sono descritte tali API.

Client per smatphone

Sono inoltre disponibile le app per Android e iOS per interagire con selfoss, ma personalmente preferisco usare la versione mobile accessibile via browser.

Ulteriori estensioni

Effettuando una ricerca su github è possibile vedere come la comunità abbia creato diverse app che si integrano tramite l’utilizzo delle API alla propria istanza di selfoss.