====== Come installare openDCN ======
OpenDCN è un'applicazione web sviluppata con il framework CakePHP (http://cakephp.org/) che è parte integrante dell'applicazione stessa ed è, quindi, distribuito con essa. Può essere installato sia su server Windows che Linux/Unix-like.
===== Requisiti di sistema =====
L'ambiente di esecuzione richiede:
* Apache 2.2.3 con mod_ssl 2.2.3 e OpenSSL 0.9.8c
* PHP 5.3
* Mysql 5.1
* Java 1.6
o versioni successive.\\
In MySQL 5.6 o versioni successive, è necessario impostare SQLMode = "" nel file di configurazione di MySQL (my.cnf)
L'ambiente client richiede:
* Browser abilitato per JavaScript
* Browser in grado di accettare i cookie
Segue un esempio di file di configurazione del Virtual Host per Apache 2.2 che mostra, di conseguenza, i requisiti per l'esecuzione di un sito openDCN
ServerName __SITENAME__
DocumentRoot "/www/sites/__BASE__/home/app/webroot"
Options FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
Allow from all
DirectoryIndex index.php index.html index.htm
Segue un esempio di file di configurazione del Virtual Host per Apache 2.4 che mostra, di conseguenza, i requisiti per l'esecuzione di un sito openDCN
ServerName __SITENAME__
DocumentRoot "/www/sites/__BASE__/home/app/webroot"
Options FollowSymLinks MultiViews
AllowOverride All
Require all granted
DirectoryIndex index.php index.html index.htm
dove %%__BASE__%% è un identificatore per l'installazione di openDCN e %%__SITENAME__%% è il valore della direttiva ServerName utilizzato per indirizzare il sito web.\\
**ATTENZIONE**: Non è possibile installare openDCN in una sottodirectory della root del virtual host, perché al momento non supporta base_url
Apache richiede i seguenti moduli (questo elenco fa riferimento ai moduli utilizzati in un ambiente Debian GNU/Linux):
* alias.load
* auth_basic.load
* authn_file.load
* authz_default.load
* authz_groupfile.load
* authz_host.load
* authz_user.load
* autoindex.load
* cgi.load
* dir.conf
* dir.load
* env.load
* mime.load
* negotiation.load
* php5.conf
* php5.load
* rewrite.load
* setenvif.load
* ssl.conf
* ssl.load
* status.load
PHP 5 richiede i seguenti moduli
* curl.so
* gd.so
* mbstring.so
* mcrypt.so
* mysqli.so
* mysql.so
* pdo_mysql.so
* pdo.so
===== Configurazione =====
1. Creare la directory principale di openDCN (denominata con l'identificativo usato al posto di %%__BASE__%% nella configurazione del virtual host di cui sopra), quindi scompattare in essa il file zip o tgz.
Se si sta installando openDCN in un ambiente in cui non è possibile modificare la configurazione del virtual host o non si ha il controllo completo sul database, come ad esempio, un servizio di hosting commerciale, allora occorre:
- modificare la struttura della directory, effettuando le seguenti operazioni:
- rinominare la cartella 'fairvote' in 'fairvote_src' e il file 'index.php' a 'index_old.php'
- spostare tutti i contenuti della directory home/app/webroot nella directory di root
- copiare il file install/paths_cfg.php nella directory root e modificarlo secondo i percorsi effettivi della vostra installazione (ad esempio quelli forniti dal service provider).
- verificare che l'utente Mysql abbia anche i seguenti privilegi sul database utilizzato:
CREATE TEMPORARY TABLES
CREATE VIEW
SHOW VIEW
CREATE ROUTINE
TRIGGER
Se non si hanno sufficienti privilegi sul database non è possibile attivare la "fusione degli utenti"
In ambiente Linux impostare i permessi rwx nel modo seguente
chmod -R 2777 home/app/tmp
chmod -R 2777 home/app/webroot/files
chmod -R 2777 home/app/webroot/dokuwiki/data
2. Creare il database Mysql e inizializzarlo con i file sql contenuti nella directory install/\\
In ambiente Linux si possono utilizzare i seguenti comandi per effettuare questa procedura velocemente
cat createdb.sql | sed "s#__BASE__#$BASE#g" | sed "s#__PASSWORD__#$PASSWORD#g" | mysql
cat createtablesdb.sql | mysql dcn_$BASE
cat createfusionusersdb.sql | mysql dcn_$BASE # Se non si hanno sufficienti privilegi sul database non importare questo file sql
cat initializedb.sql | sed "s#__BASE__#$BASE#g" | mysql dcn_$BASE
In ambiente Windows sostituire tutte le occorrenze di %%__BASE__%% con il nome della propria installazione openDCN prima di applicare i comandi SQL
3. Copiare il file home/app/config/app_config.php.example e rinominarlo app_config.php (nella stessa directory)
Modificarlo in base alle proprie impostazioni. Il file contiene commenti che spiegano il significato delle possibili variabili da impostare.
In particolare, è necessario impostare la variabile 'localdomain' con il nome scelto per la propria installazione openDCN
Configure::write('localdomain', '__BASE__');
Sostituire %%__BASE__%% con il nome della propria installazione come al punto precedente
Se non si hanno sufficienti privilegi sul database impostare a true la seguente variabile
Configure::write('disable_fusion_user', true);
4. Copiare il file home/app/webroot/doku_conf/local.php.example e rinominarlo local.php (nella stessa directory).
Impostare la stringa 'http://SITENAME/' nella variabile
$conf['plugin']['authopendcn']['host']
dove SITENAME è l'indirizzo del sito web che si sta configurando
Impostare una stringa segreta nella variabile
$conf['plugin']['authopendcn']['key']
La stessa stringa andrà impostata nella variabile 'dokuwiki_secret_key' (al posto di 'changeme') presente nel file app_config.php
Configure::write('dokuwiki_secret_key', 'changeme');
===== Primo login =====
Una volta che il sistema è stato installato ed è stato modificato il file app_config.php si può procedere al primo login.\\
Caricare la pagina %%http://__SITENAME__/%% e accedere utilizzando l'account dell'Amministratore\\
Username: admin\\
Password: admin
------------------
===== Consultazione certificata (FairVote) =====
FairVote è il nome del modulo client/server per la gestione delle consultazioni certificate. Può essere utilizzato anche come applicazione indipendente.\\
Il lato server è costituito da tre agenti ciascuno dei quali deve svolgere un ruolo tra Registrar, Forwarder o Collector.\\
Il Registrar:
* Verifica i dati di autenticazione dell'utente (username e password)
* Controlla se l'utente è ammissibile alla consultazione. Tali controlli vengono effettuati con una richiesta al server di autenticazione
* Rilascia i token cifrati per l'invio delle risposte
* Verifica l'autenticità dei token rilasciati
Il Forwarder:
* Raccoglie risposte anonime e cifrate (l'utente è autenticato ma non è riconoscibile e le risposte sono cifrate)
* Verifica attraverso i token cifrati che l'utente sia valido
* Disaccoppia l'identità dell'utente dalle sue risposte
Il Collector:
* Raccoglie le risposte anonime ricevute dal Forwarder
* Verifica, attraverso token cifrati, se le risposte inviate sono valide
* Compila i risultati della consultazione
Una consultazione è completamente definita da un "Manifesto", che è un documento XML che contiene tutti i parametri della consultazione. Questo documento è firmato digitalmente dall'Amministratore della consultazione.\\
Se Fairvote è utilizzato come modulo, openDCN redige automaticamente il Manifesto e svolge il ruolo di server di autenticazione.
==== Installazione di FairVote ====
In home/app/webroot/fairvote è possibile trovare i seguenti file:
* Signer.jar utility per la firma del manifesto
* Pilot.jar utility per avviare gli agenti in attesa di un ruolo
* Console.jar utility per la gestione della consultazione (inizializzazione, cancellazione, pubblicazione dei risultati ...)
* Applet.jar il client per la lettura manifesto e la partecipazione alle consultazioni
Si noti che la directory fairvote/ è presente al solo scopo di distribuire i sorgenti e di fornire documentazione e può essere assente in un ambiente di produzione.
1. Creare un manifesto (in fairvote/doc/ è possibile trovare un esempio). Il modulo di consultazione certificata di openDCN lo fa in automatico con il comando "pubblica consultazione" nella pagina di configurazione dello strumento.\\
Il Manifesto deve essere pubblicato su Web in una posizione che possa essere letta dall'Applet. OpenDCN di default lo pubblica nella directory home/app/webroot/fairvote/admin/files/ \\
I file control.php e getfile.php possono essere utilizzati per gestire l'upload e il download dei manifesti da un repository protetto da account per le modifiche. \\
Le variabili fairvote_repository nell'app_config.php consentono di impostare username e password per l'amministratore (fairvote_editor), l'URL del repository e il download dell'Applet.\\
Fairvote assume che la Java Virtual Machine venga eseguita in ambiente con codifica UTF-8 predefinita. Se così non fosse, eseguire "java" come "java -Dfile.encoding=utf-8"
2. Creare il database Mysql e inizializzarlo con il file createtables.sql contenuto nella directory fairvote/utils/contrib/
==== Signer.jar ====
Utilizzare Signer per firmare il manifesto con la firma memorizzata in un keystore.\\
OpenDCN chiama il Signer con il comando "pubblica consultazione" nelle pagine di modifica dello strumento di consultazione certificata.\\
Per eseguirlo da linea di comando:
java -jar Signer.jar unsignedManifest.xml keystoreFile pwKeystore aliasPrivateKey pwPrivateKey aliasPublicCert > signedManifest.xml
==== Pilot.jar ====
Utilizzare Pilot per avviare gli agenti per la gestione della consultazione.
Deve essere presente su tutti i server coinvolti nella consultazione, con il proprio file di configurazione.
Per esempio, si può avere un Pilot.jar su una macchina server singola che esegue Registrar, Forwarder e Collector o tre macchine server che eseguono un Pilot.jar ognuno con un ruolo diverso (Registrar, Forwarder o Collector).\\
Necessita di un file di configurazione (un esempio è nella directory fairvote/doc/) e avvia n server ognuno con il ruolo definito nel manifesto quando viene chiamato da Console.jar
java -jar Pilot.jar config.xml
==== Console.jar ====
Console.jar invia comandi agli agenti (avviato da Pilot.jar)\\
openDCN lo usa attraverso i link della pagina /polls/edit/id (dove id è l'identificativo della consultazione).
* Publish/Unpublish
* Flush
* dumpPollResults
Console.jar può essere utilizzato da linea di comando. Ad esempio per avviare una consultazione:
java -jar Console.jar installVotazione signedManifest.xml editorCredential.xml
"installVotazione" è uno dei comandi accettati: legge il file signedManifest.xml e lo usa per inviare il comando di installazione della consultazione agli agenti, mentre editorCredential.xml contiene le credenziali dell'editor del manifesto.\\
Dopodiché gli utenti possono avviare l'Applet.jar e partecipare alla consultazione.
Console.jar accetta i seguenti comandi:
|installVotazione | installa una consultazione|-
|flushVotazione | invia i risultati all'agente Collector|-
|dumpResultVotazione| produce un documento XML contenente i risultati della consultazione|-
|removeVotazione | elimina una consultazione (con tutte le relative risposte)|-
Usare l'opzione -h (o NomeComando -h) per visualizzare un elenco di tutti i comandi accettati.\\
openDCN chiama Console.jar attraverso i link della pagina /polls/edit/id (dove id è l'identificativo della consultazione)
==== Applet.jar ====
Applet.jar è l'applet da includere nella pagina web che mostra la consultazione
Accetta i seguenti parametri:
|URL |(obbligatorio), è l'url del manifesto firmato|-
|CMD |(obbligatorio), vale una delle due opzioni: |-
|AUTH_TOKEN|(opzionale), è un token usa e getta necessario per partecipare alla consultazione (presume che l'utente sia già registrato)|-
|SAML |(opzionale) è una SAMLResponse, codificata in base64, che può essere utilizzata come autenticazione|-
openDCN mostra Applet.jar caricando la pagina /polls/view/id (dove id è l'identificativo di consultazione)