Iniziare con Virtualenv

Chi avesse già familiarità con virtualenv e easy_install può passare alla sezione succesiva.

Ogni cosa sarà impostata in un ambiente isolato e non avrà nessun effetto sul sistema al di fuori delle cartelle interessate da questo tutorial. Nel caso in cui non sia di nostro gradimento potremo tranquillamente cancellare questa cartella.

La prima cosa da fare è recuperare virtualenv e creare un ambiente. Prendere perciò virtualenv.py ed eseguire:

$ python virtualenv.py --no-site-packages DelivTest

Questo creerà un ambiente in DelivTest/ e installerà easy_install. Esiste anche un nuovo interprete di Python in DelivTest/bin/python - ogni cosa in DelivTest/bin/ verrà collegata a questo ambiente. Esso farà uso di librerie dell'ambiente e ne installerà altre all'interno dello stesso.

Da notare che è possibile lanciare source DelivTest/bin/activate per cambiate $PATH, quindi ogni voltà che si esegue Python, easy_install, ecc. lo si lancerà dall'ambiente che abbiamo creato.

Installare il software

A questo punto la guida originale che stiamo seguendo, http://deliverance.openplans.org/quickstart.html , ci indica un altro installer da usare e prosegue con altre istruzioni, che però creano qualche problema. Ci scostiamo quindi per questo paragrafo dalla nostra guida e installeremo Deliverance da svn, nel modo seguente (su Ubuntu):

# Get development libraries
sudo apt-get install libxml2-dev libxslt-dev
# Create virtualenv 
virtualenv --no-site-packages deliverance_svn
cd deliverance_svn
# Install latest version of setuptools to prevent error "global name 'log' is not defined"
. bin/activate
sudo easy_install -U setuptools
deactivate
# Checkout deliverance from svn
svn co http://codespeak.net/svn/z3/deliverance/trunk/ deliverance
cd deliverance
# Install deliverance
../bin/python setup.py install
# Install paster in virtualenv
../bin/easy_install PasteScript
cd ..
# Create deliverance instance
./bin/paster create -t deliverance DelivTest
# Answer the questions...
./bin/deliverance-proxy DelivTest/etc/deliverance.xml

(fonte: http://keeshink.blogspot.com/2009/03/installing-deliverance.html)

Riprendiamo ora la guida originale che stavamo seguendo.

Creare una Configurazione

A questo punto il software è installato, ma per eseguirlo è necessario prima configuralo. Per creare la configurazione lanciare:

$ DelivTest/bin/paster create -t deliverance DelivTest
Selected and implied templates:
 deliverance#deliverance Basic template for a deliverance-proxy setup

Variables:
 egg: TestEnv
 package: testenv
 project: TestEnv
Enter host (The host/port to serve on) ['localhost:8000']:
Enter proxy_url (The main site to connect/proxy to) ['http://localhost:8080']:
Enter proxy_rewrite_links (Rewrite links from sub_host?) ['n']:
Enter password (The password for the deliverance admin console) ['']: test
Enter theme_url (A URL to pull the initial theme from (optional)) ['']: http://mysite.com
Creating template deliverance
...

Esso richiederà alcune informazioni:

host:

L'indirizzo dal quale Deliverance sarà accessibile. Considera che localhost (o 127.0.0.1) significa che è possibile connettersi solo dalla macchina stessa.. Se si desidera essere visibili dall'esterno si deve usare 0.0.0.0.

proxy_host:

Qui vanno tutte le richieste, http://localhost:8080 è un default generico per i server. in alternativa è possibile fornire un host remoto e un percorso, ad esempio http://mysite.com/blog

proxy_rewrite_links:

Se si cerca di accedere ad un sito il quale non si aspetta di essere oggetto di proxying, allora i link potrebbero essere sbagliati. Per procedere alla riscrittura dei link immettere qui una Y. Non è sicuro che funzioni al 100% (ad esempio link messi in Javascript), ma può andare bene per fare esperimenti.

password:

É la password per accedere alla logging console. La username è sempre admin. Ulteriori login possono essere aggiunti o modificati in seguito.

theme_url:

Se si desidera basare il proprio theme su una pagina già esistente è possibile inserire qui l'URL della pagina in questione. Deliverance andrà a prendere la pagina con tutto il CSS e le immagini, in modo da poterle editare sul posto. In alternativa entrerà in uso un tema molto semplice.

Una volta assegnati questi valori verrà attivato un layout di base con il file etc/deliverance.xml per la configurazione, più un tema in theme/theme.html.

Il server si attiva con:

$ ./bin/deliverance-proxy ./etc/deliverance.xml

Il sito sarà accessibile all'indirizzo http://localhost:8000 e ci si potrà autenticare al seguente indirizzo http://localhost:8000/.deliverance/login

Una volta autenticati con la password inerita durante la configurazione, sarà possibile visitare la pagina http://localhost:8000/?deliv_log per visualizzare un registro di tutto quello che Deliverance sta facendo (si trova a fondo pagina).

Usare un Buildout

Gaël Pasgrimaud ha scritto le istruzioni per l'installazione di Deliverance usando buildout e pip. Le indicazioni di massima sono:

[buildout]
# the cache dir is used by buildout & pip
download-cache = download
parts = eggs

[eggs]
recipe = gp.recipe.pip

# eggs installed by pip (also add the Deliverance bundle)
install =
 Cython
 --install-option=--static-deps lxml==2.2alpha1
 http://deliverance.openplans.org/dist/Deliverance-snapshot-latest.pybundle

# eggs installed by zc.recipe.egg
eggs =
 Paste
 pyquery

Questo usa la sua ricetta buildout gp.recipe.pip.

Correggere le Regole

La prima sezione rigurdante i primi passi da seguire finisce qui; per comprendere le regole è necessario proseguire la lettura della documentazione, in particolar modo la sezione Regola e Tema.

A Proposito di Piattaforme

Viviamo in un'era di piattaforme. Gli sviluppatori decidono spesso di utilizzare una piattaforma come base per il proprio lavoro, spesso, all'interno di queste piattaforme,  si trovano alcune cose vecchie derivanti da piattaforme precedenti. Obiettivo dello sviluppatore dovrebbe essere sempre quello di eliminare le parti vecchie e riscriverle per le nuove piattaforme. Purtroppo questo obiettivo viene raramente raggiunto in un tempo decente e spesso, prima di essere portato a termine è ormai tempo di passare alla prossima piattaforma.

Ma perché trasportare tutto sulla piattaforma più nuova? Presumibilmente perché è quella con l'architettura migliore, nonché quella più conosciuta e usata. Se però queste fossero le sole ragioni sarebbe difficile giustificare la riscrittura di un software. Spesso l'esigenza nasce dal fatto che i nostri sistemi presentano problemi di interoperatività. Sincronizzare più template su tutte le piattaforme non è per niente una cosa facile: necessità di login multipli, navigazione irregolare e incompleta,... Una funzionalità che influisca sulle pagine (commenti, status di login, status dei carrelli della spesa, ecc.) non è disponibile ovunque.

Un conflitto simile sorge quando si valuta come aggiungere nuove funzioni ad un sito. Ad esempio, nel caso in cui vogliate aggiungere un blog, come procedete?

1. Usate il miglior software per la creazione di blog esistente?
2. Usate qualcosa nativo della vostra piattaforma?
3. Scrivete qualcosa da soli?

La maggior parte delle risposte saranno la 2 o la 3, proprio perché integrare qualcosa di estraneo sulla propria piattaforma sarebbe troppo difficile. Una decisione del genere porterebbe ad avere vari tipi diversi di blog sparsi su tutte le piattaforme, ma gli utenti di quel determinato blog sarebbero probabilmente solo un sottoinsieme degli utenti della piattaforma "madre". Tutto ciò comprometterebbe seriamente la possibilità per le soluzioni vincenti di emergere e avere successo. Un software basato su una piattaforma è limitato dall'adozione della piattaforma stessa.

Non tutti i software hanno una piattaforma. Questi tendono ad essere le applicazioni web di maggior successo, come Trac e WordPress (solo per citarne un paio) ampiamente dimostrano.

Tutto questo non vuol dire però che vengono utilizzati solo perché sono i migliori nel loro genere. La vera ragione è che diventano essi stessi delle piattaforme. WordPress e Trac sono praticamente dei CMS. Applicazioni prorogabili, se di successo, diventano la loro stessa piattaforma. Non per formulare accuse, non sono per forza peggio do ogni altra piattaforma, è solo per far notare che questo tipo di passaggio può avvenire.

Oltre le Piattaforme, o una Piattaforma Migliore

Uno degli scopi maggiori di Deliverance è quello di muoversi oltre le piattaforme. È un "integration tool" che permette ai framework o linguaggi diversi di essere integrate in modo garbato.

Esistono alcune ragioni di base per cui la gente usa le piattaforme:

1. Un aspetto comune attraverso il sito.
2. Una navigazione coesiva.
3. Indicizzazione dell'intero sito.
4. Autenticazione e account utente condivisi.
5. Funzionalità trasversali (ad esempio lasciare commenti).

Deliverance è specificatamente rivolto al punto 1, in quanto fornisce un aspetto comune attraverso il sito. Può essere utile col punto 2, dato che permette una gestione maggiormente centralizzata della navigazione senza fare affidamento solo su una navigazione secondo applicazione (sebbene una navigazione di questo tipo sia ancora essenziale per navigare le singole applicazioni. I punti 3, 4 e 5 invece non riguardano Deliverance (almeno non ancora).

Deliverance applica un theme comune a tutte le applicazioni del vostro sito. La sua unità base di astrazione è HTML, non utilizza un particolare linguaggio di template e non sa cosa sia un oggetto. L'HTML è prodotto da qualunque applicazione web. Il mezzo di comunicazione di Deliverance è HTTP. Non richiama funzioni o crea richiesta di oggetti [*]. Di nuovo, HTTP è universale.

Deliverance offre anche la possibilità di includere output da posizioni multiple. In ogni caso esiste un theme, una pagina HTML semplice, e un "content", qualunque cosa la suddetta applicazione risponda. È inoltre possibile includere output da altre parti del sito, il più delle volte contenuti di navigazione che possono essere gestiti separatamente. Tutte queste parti possono essere dinamiche - di nuovo, Deliverance si occupa solo di HTML e HTTP, non si preoccupa di ciò che la risposta produce.

C'è molta somiglianza con sistemi costruiti su XSLT, eccetto senza XSLT [+] e senza XML. A rigor di termini è possibile applicare XSLT a qualunque markup analizzabile, anche HTML, ma il modo più comune (o quantomeno quello di cui si parla di più) di applicare l'XSLT è usare l'output XML "semantico" trasformato in HTML. Deliverance non cerca di comprendere le semantiche delle applicazioni, ma fa affidamento sul fatto che esse forniscano una adeguata "presentazione" di qualunque semantica sia in possesso la suddetta applicazione. Una presentazione è più universale delle semantiche.

Sebbene Deliverance dia il meglio di sé lavorando con applicazioni così come sono, senza porre particolari richieste a riguardo, non è comunque perfetto. Eventuali conflitti con il CSS potrebbero essere un grosso problema. Alcune applicazioni hanno una struttura tale che risulta difficile lavorarci assieme. Deliverance non è in grado di generare alcun tipo di contenuto, ma solo di manipolare quelli esistenti, il che spesso significa trovare nuovi modi di generare un contenuto o essere sicuri di avere a disposizione un luogo dove immagazzinarlo (come nel caso della navigazione). Ecco perché si può sostenere che Deliverance non elimini il bisogno di una piattaforma, ma che sia la piattaforma di sé stesso. In sostanza Deliverance tenta di essere una piattaforma migliore, cioè universale, piuttosto che più potente. La maggior parte dei sistemi di templating sono molto più potenti delle trasformazioni di Deliverance. Può essere utile avere accesso agli oggetti sottostanti per ottenere il markup. Ma Deliverance non si occupa di questo, poiché implementa solamente cose che possono essere applicate a ogni fonte di contenuto. I file statici sono completamente realizzabili e sfruttabili su Deliverance, così come qualunque applicazione scritta in Python, PHP, o addirittura un'applicazione ospitata su un servizio completamente diverso è anch'essa utilizzabile attraverso Deliverance.

Parti Mancanti

Come accennato in precedenza, Deliverance manca di due importanti vantaggi per una piattaforma. Di seguito cercheremo di trattare quelli che riteniamo essere gli aspetti essenziali di questo argomento, con la speranza che presto Deliverance o altre applicazioni complementari siano in grado di porvi rimedio. Suggeriamo inoltre alcune linee di sviluppo che potrebbero essere più facili di altre.

Indicizzare l'Intero Sito

Come al solito ogni applicazione ha un'idea di quali siano le pagine interessanti all'interno di essa. La maggior parte delle applicazioni infatti possiede un set di pagine "non interessanti", o pagine transitorie. I risultati di una ricerca, ad esempio, sono transitori. Un'applicazione riconosce anche quando appaiono nuove pagine e quando ne svaniscono altre. Un indice a tutto sito di queste pagine permetterebbe cose come mappe del sito, ricerche su più applicazioni e la possibilità di resoconti trasversali.

Esiste un'interessante eccezione alla conoscenza che un'applicazione ha di sé, e cioè che i risultati di ricerca sono generalmente noiosi. Ma il risultato di una ricerca basato su una categoria potrebbe ancora essere interessante. La differenza tra "ricerca" e "resoconto" è prevalentemente discrezione di ognuno. Una caratteristica importante è che le applicazioni non dovrebbero essere le uniche entità a poter segnare pagine interessanti. Liste di risorse gestite manualmente aventi la possibilità di indicare specifiche applicazioni possono permettere di modificare il sito in modo facile e utile. L'ideale sarebbe che anche risorse totalmente esterne potessero essere incluse, così come risorse su un altro sito.

Per indicizzare sono necessari sia gli eventi (segnalare la creazione, aggiornamento o cancellazione di un'entità/pagina) che una lista delle entità (così che l'indice possa essere completamente rigenerato). Un modo semplice di fornire una lista di entità potrebbe essere Google Site Map XML resource. Segnalare gli eventi è molto più complicato, ragion per cui non ci addentreremo molto nell'argomento; un prodotto per la gestione degli eventi, chiamato Cabochon, è comunque in fase di sviluppo.

Una cosa che l'indicizzazione può fornire è un modo di usare microformati. I microformati sono interessanti, ma profondamente inutili per la maggior parte dei siti. Si può segnare un contenuto, ma nessuno farà niente di interessante con quella segnalazione. Se si potesse codificare un indicizzatore che fosse in grado di tenere aggiornati tutti i contenuti di un sito si potrebbero creare interessanti risultati come una mappatura trasversale delle applicazioni.

Condividere l'Autenticazione e gli Account Utente

L'integrazione è uno dei compiti più comuni e irritanti quando si superano i confini di una piattaforma. Sistemi quali Open ID offrono la possibilità di unificare autenticazioni incrociate di siti, ma in ogni caso non risolvono il problema di un singolo sito con molte applicazioni.

In HTTP esiste un protocollo elementare per le autenticazioni, uno che può lavorare con un sistema come Deliverance; esistono inoltre molti altri prodotti (come repoze.who) che funzionano in questo modo. Il modus operandi è il seguente:

• L'username loggata è mandata in un header, ad esempio X-Remote-User. È necessario un qualche tipo di firma per fidarsi di questo header (Deliverance è in grado di filtrare tale header nelle richieste in entrata, ma se Deliverance venisse rimosso si creerebbe un buco nella sicurezza).
• Se l'utente non è loggato e l'applicazione richiede il login, la suddetta applicazione emetterà un responso di tipo 401 Unauthorized. Dovrebbe settare l'header WWW-Authenticate, probabilmente ad alcuni valori indicanti che l'intermediario dovrebbe determinare il tipo di autenticazione. In alcuni casi è richiesta un tipo di autenticazione HTTP (generalmete Basic o Digest) poichè i login basati sul cookie sono anch'essi a stati (ad esempio negli API, o per l'accesso WebDAV).
• Quando un utente è loggato ma non ha i permessi, l'applicazione invierà semplicemente una risposta 403 Forbidden. L'intermediario in questo caso non dovrebbe compiere alcuna azione (sebbene sarebbe forse utile aggiungere un link di logout al messaggio). Da segnalare che alcuni sistemi utilizzano 401 per indicare Forbidden, cosa che crea problemi a non finire.

Alcune applicazioni permettono questo schema di autenticazione, altre no. In ogni caso questo schema dovrebbe essere sufficientemente generale da poterne giustificare l'adozione nel modo di lavorare delle applicazioni.

Questo tratta di autenticazioni condivise, ma l'unica informazione passata in giro è il nome utente. Informazioni sull'utente - vero nome, e-mail, homepage, permessi, ecc - non vengono condivisi in questo modello.

È possibile aggiungere qualcosa come una location interna al nome utente. Ad esempio: X-Remote-User: bob; info_url=http://mysite.com/users/bob.xml. Sarebbe compito dell'applicazione fare una sotto richiesta per portare quell'informazione. Questa operazione potrebbe rivelarsi inefficiente, anche se un'adeguata operazione di caching potrebbe andare bene. Molte applicazioni però richiedono un grande sforzo per avere una registrazione completa di tutti gli utenti. Cambiarla però potrebbe essere molto più difficile che cambiare lo schema di autenticazione. Un sistema più agevole potrebbe essere qualcosa di simile a ciò che viene descritto  in Indicizzare l'Intero Sito: fornire una lista completa del sito così come degli eventi quando gli utenti sono creati, aggiornati o cancellati, e permettere alle applicazioni di mantenere i loro database utenti privati ma sincronizzati.

Un comune sistema di permessi è un altro livello di integrazione. Un modo di gestire la faccenda sarebbe se le applicazioni avessero un set di azioni pubblicato che potessero essere eseguite, e che la persona integrante l'applicazione potesse mappare le azioni dei ruoli/gruppi sul sistema.

Funzionalità ad Effetto Trasversale

Questo parte richiede una piccola spiegazione. Si tratta di una funzionalità che ha effetto su più parti di un sito. Un esempio potrebbero essere i commenti, dove si desideri che il sistema di commento sia applicabile ad una serie di entità (anche se probabilmente non a tutte). Oppure notifiche di aggiornamento pagine, o la fornitura di feed riguardanti cambiamenti delle entità.

Si potrebbe anche voler aggiungere applicazioni come Google Analytics a tutte le pagine, ma la funzione che dovrebbe svolgere è già eseguita dal theming di Deliverance. L'insieme di Deliverance si occupa efficacemente dei contenuti universali, ma non di contenuti (o sotto richieste) che dovrebbero essere presenti solo in una parte della pagina.

Un altro modo potrebbe essere includere una parte di un documento in un altro documento per rimando, dove una pagina può richiedere specificatamente alcune altre risorse da includere nella pagina. Una semplice sotto richiesta dovrebbe bastare per svolgere quest'operazione, ma molte applicazioni rendono l'inserimento di alcuni elementi segnalati abbastanza semplice (ad esempio editando i loro template), ma comunque in modo non così semplice come una sotto richiesta. A tal proposito esiste un prodotto chiamato Transcluder.

Usando Deliverance è altresì possibile implementare questa funzione senza apportare modifiche all'applicazione, sebbene ciò significhi aggiungere una configurazione - un'applicazione scritta per essere inserita un una pagina via Deliverance, e una regola di Deliverance che fissi tutto assieme (ma se scritta male bisognerà provvedere al debug).

Altre Convenzioni

Inoltre altre convenzioni simili a piattaforme renderebbero la vita di un integratore molto più facile.

Personalizzazione del Template

Mentre Deliverance si occupa dell'aspetto della pagina, la parte più interna del contenuto viene lasciata all'applicazione. Se si desidera apportare delle piccole modifiche si dovrà comunque personalizzare il template dell'applicazione.

Sarebbe meraviglioso se le applicazioni potessero fare rapporto sull'utilizzo di un file nella costruzione di una richiesta, e se usassero un percorso di ricerca comune così da poter annullare quei file facilmente.

Backup e Manutenzione

Il processo può essere gestito tramite software come Supervisor, e non è detto che in futuro Deliverance non possa inglobare proprio Supervisor.

Ma anche così i normali backup di sistema sarebbero comunque importanti. Ogni applicazione svolge i backup alla sua maniera. Operare backup in modo convenzionato sarebbe l'ideale. Avere delle convenzioni per ristabilire i backup sarebbe anche meglio.

Molti sistemi inoltre richiedono una manutenzione periodica - compattazione dei database, ricerca di eventuali problemi di integrità, ecc. Alcuni sistemi unificati come cron potrebbero essere d'aiuto, sebbene le applicazioni abbiano comunque le capacità di occuparsene dall'interno con azioni ad hoc.

Errori Comuni

Quando si lavora con un sistema avente molti componenti che possono non funzionare correttamente è importante essere al corrente di tali problemi. Se gli errori finiscono in uno di 10 log file, probabilmente nessuno se ne sta curando.

Un software dal nome ErrorEater, che tra l'altro lavora con Supervisor, è al momento in fase di progettazione e potrebbe risolvere molto di questi problemi. Le applicazioni devono essere modificate in modo da emettere gli errori in un formato specifico che Supervisor possa comprendere, ma in genere non è un'operazione troppo complessa.

Farming

Si parla di farming di un'applicazione quando un'istanza di un'applicazione è in grado di supportare molti siti, siano essi aventi il loro proprio dominio o solo progetti distinti. Alcuni esempi sono Trac, il quale supporta più progetti in una sola istanza, o WordPress MU, che supporta molte istanze WordPress che girano da un singolo database e base di codice.

Sarebbe bello poter aggiungere un semplice header a d una richiesta, come X-Project-Name: foo, il quale potrebbe essere usato da tutti questi prodotti per sdelezionare il sito (o sotto-sito o progetto o qualunque altra unità organizzativa). Successivamente si potrebbe mappare i nomi dei domini, i percorsi, o altri aspetti di una richiesta in una sola volta e le applicazioni potrebbero tutte costantemente ocnsumarlo.

(Per quanto riguarda openplans.org,  X-OpenPlans-Project viene usato internamente e si personalizzano patch per vari progetti per il suo supporto, ma tutto viene fatto ad hoc.)

Note

[*]  Questo non è del tutto vero, Deliverance usa WSGI, un'astrazione di livello Python di chiamate HTTP.
[+]  In passato è successo, e forse si ripeterà in futuro, che Deliverance sia stato compilato seguendo regole XSLT. Quindi Deliverance potrebbe addirittura essere visto come un semplice linguaggio di trasformazione che compila in XSLT.