VFront - Guida all'installazione

VFront - Guida all'installazione 2 novembre 2007 Versione documento: 1.03 Indice 1 Licenza di questa documentazione 3 2 Requisiti di base 3 2.1 Nota importante per gli utilizzatori di PostgreSQL........ 4 3 Per chi ha fretta... 4 4 Copia dei le ed impostazione dei diritti a le e cartelle 5 5 Il le di congurazione 6 5.1 Connessione al database....................... 6 5.2 Impostazioni di autenticazione................... 7 5.2.1 Autenticazione mediante database presente sullo stesso server (solo MySQL).................... 8 5.2.2 Autenticazione mediante database esterno e/o residente su altro server (MySQL, PostgreSQL, ODBC)....... 8 5.2.3 Autenticazione mediante LDAP o Active Directory... 9 5.2.4 Autenticazione mediante SOAP (sperimentale)...... 9 5.3 Sezione SMTP e e-mail....................... 10 5.4 Sezione Debug............................ 10 5.5 Sezione Log.............................. 11 5.6 Sezione localizzazione: lingua e codica.............. 11 5.7 Sezione Path............................. 12 5.8 Sezione FOP............................. 12 5.9 Sezione Allegati e Link....................... 13 5.10 Sezione Misc............................. 13 5.11 Inclusione del le di congurazione................. 14 6 Procedura di installazione automatica 14 7 Procedura di installazione manuale 14 1

8 Dopo l'installazione 15 8.1 Inizializzazione del sistema..................... 15 8.2 Test impostazioni VFront...................... 15 2

1 Licenza di questa documentazione Copyright (c) 2007 Marcello Verona <marcelloverona@gmail.com> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". 2 Requisiti di base Per funzionare VFront necessita del seguente software: Server web Apache 2.x (l'applicazione è stata sviluppata e testata per il server Apache 2.x, potrebbe funzionare con altri server web) MySQL 5.x oppure PostgreSQL 8.x (Attenzione! il supporto a PostgreSQL è in fase alpha) PHP versione 5.x Sono richiesti inoltre i seguenti moduli per PHP: php_mysqli (MySQL Improved) - qualora si utilizzasse un database mysql (o ci si volesse autenticare tramite server mysql esterno) php_pgsql (libreria Postgres) - qualora si utilizzasse invece un database postgresql (o ci si volesse autenticare tramite server postgresql esterno) Opzionalmente si richiedono inoltre i seguenti moduli php_gd2 - GD library versione >=2.x php_gettext per la traduzione dell'interfaccia. In caso non sia presente la libreria sarà utilizzata una implementazione di gettext in versione interpretata php_xsl per l'utilizzo delle trasformazioni XSL lato server. Qualora non si avesse la possibilità di usare questa estensione si potranno comunque utilizzare le trasformazioni lato client. php_ldap - qualora si volesse impostare l'autenticazione esterna via LDAP php_odbc - qualora si volesse impostare l'autenticazione esterna via ODBC php_soap - qualora si volesse impostare l'autenticazione esterna via SOAP (sperimentale) 3

Per le operazioni relative alla reportistica è richiesto il parametro allow_url_fopen impostato su TRUE. Il parametro è impostabile nel le php.ini oppure nel le httpd.conf (non ad esempio in un.htaccess). La sezione statistiche utilizza invece PEAR (http://pear.php.net/) per la generazione dei graci. Sono richiesti dunque, oltre a PEAR i pacchetti: Image/Graph (http://pear.php.net/package/image_graph ) Image/Canvas (http://pear.php.net/package/image_canvas ) come dipendenza di image/graph Nota bene: al momento in cui si scrive il pacchetto Image_Graph è alla release 0.72. Questa release ha un piccolo bug nella generazione delle etichette dei graci a torta, che non vengono mostrate senza generare alcun errore. Per risolvere il problema utilizzare la versione CVS del le Image/Graph/Plot/Pie.php recuperabile dall'indirizzo http://cvs.php.net/viewcvs.cgi/pear/image_graph/graph/ Plot/Pie.php?content-type=text%2Fplain&view=co 2.1 Nota importante per gli utilizzatori di PostgreSQL VFront fa grande uso delle viste dello schema information_schema. Ci sono alcune viste che possiedono dei bug per quanto riguarda l'attribuzione dei diritti, errori documentati sui forum del sito di Postgres 1. Le viste sono key_column_usage e table_contraints. Questi bug si sono trascinati in numerose versioni di Postgres dalla 7.4 (nella quale è stato aggiunto l'information_schema) alla 8.2. La conseguenza delle viste bacate di Postgres su VFront è l'impossibilità di rilevare la presenza di chiavi primarie e chiavi esterne nelle tabelle, compromettendo il funzionamento dell'intera applicazione. Il problema non si presenta nel caso di utilizzo di un utente SUPERUSER come utente di VFront per leggere il database, scelta peraltro sconsigliata per ragioni di sicurezza. Per risolvere il bug è possibile eseguire lo script presente nella cartella _install dal nome _install/postgres.information_schema.bugfix.sql come utente superadmin (ad es. postgres). Lo script (che ricrea le viste con le giuste attribuzioni di diritti) funziona sicuramente nella versione 8.1. Per altre versioni è forse necessario apportare alcune modiche al bugx. 3 Per chi ha fretta... 1. Estrai i le di VFront sulla cartella htdocs di Apache 2. Apri il le conf/conf.vfront.php e imposta correttamente i parametri seguendo i commenti del le 1 Si legga ad esempio http://archives.postgresql.org/pgsql-bugs/2006-12/msg00168.php e http://archives.postgresql.org/pgsql-hackers/2007-08/msg00329.php 4

3. Apri il le inc/conn.php e modicalo nelle prime righe per includere il path reale del le di congurazione conf.vfront.php 4. Esegui l'installazione da http://nome_del_server/path_vfront/_install/ 5. Accedi all'amministrazione di Vfront, inizializzalo e congura da interfaccia graca diritti e tabelle. 6. Appena hai più tempo leggiti il resto del documento... 4 Copia dei le ed impostazione dei diritti a le e cartelle Scompattare l'archivio di VFront nella directory sottoposta a browsing. struttura della directory dovrebbe apparire così: La VFRONT_ROOT - _install - admin - conf - files -- docs -- tmp -- xls_custom - html - img - inc - js - plugins -- FCKeditor -- phpgettext -- phpmailer -- ods - stats - sty - tmp - usr - xml Alcune cartelle devono essere scrivibili da Apache. Queste sono: files e le sue sottocartelle html tmp 5

Qualora si volesse utilizzare il debug attraverso il l rpc.debug.txt (si veda oltre per una descrizione) anche questo le deve essere accessibile in scrittura da Apache. 5 Il le di congurazione Il le di congurazione si chiama conf/conf.vfront.php. Per ragioni di sicurezza, si suggerisce di spostare la cartella conf in un'area del server non sottoposta a browsing. Attraverso il le di congurazione si possono impostare gran parte dei parametri di VFront. Altri parametri relativi all'uso ed all'aspetto saranno impostabili mediante l'area di amministrazione e la congurazione delle variabili della tabella "variabili". 5.1 Connessione al database La prima sezione del le di congurazione è relativa alla connessione al database. E' possibile scegliere se utilizzare VFront come front-end di un database MySQL 5.x oppure PostgreSQL 8.x. Si ricorda che mentre il supporto per MySQL 5.x ha avuto numerosi test ed applicazioni reali, il supporto per PostgreSQL è allo stato attuale ancora instabile e da considerarsi in fase alpha. I parametri richiesti sono: $db1['dbtype']="mysql"; // indica la tipologia di database: può essere "mysql" oppure "postgres". // DEVE essere specificato $db1['host']="localhost"; // host del server: $db1['port']="3306"; // porta del server: di default 3306 per MySQL e 5432 per PosgreSQL $db1['user']="nomeutente"; // utente per la connessione al database $db1['passw']="segreta"; // password per la connessione al database 6

$db1['dbname']="banca"; // nome del database: nel caso di postgres utilizzare "public", // cioè il nome dello schema $db1['frontend']="vfront_test"; // nome del database di VFront. // In postgres corrisponde al nome dello schema (si suggerisce "frontend") $db1['postgres_dbname']="nome_database"; // nome reale del database (solo nel caso si utilizzi Postgres) 5.2 Impostazioni di autenticazione VFront permette l'autenticazione mediante la propria tabella "utente", oppure mediante altro sistema. La logica di autenticazione e quella di accreditamento di diritti dell'utente sono infatti disgiunte. Quando si fa un'autenticazione esterna (ad esempio mediante LDAP) se l'utente esiste viene automaticamente autenticato su VFront. Il passaggio successivo sarà l'accreditamento di diritti mediante la tabella utente: qualora l'utente esistesse su LDAP e non sulla tabella utente verrà automaticamente iscritto in questa, e gli saranno attribuiti i diritti di default (gruppo 0). Per maggiori informazioni sull'uso dei gruppi e i diritti degli utenti si rimanda alla documentazione di VFront. Il parametro per l'autenticazione è $conf_auth['tipo_external_auth']= ; Se impostato = oppure =null l'autenticazione avverrà mediante il database di VFront e la sua tabella utente. Gli altri parametri possibili al momento sono db : indica un'autenticazione tramite altro database presente sullo stesso server (solo MySQL) db_ext : indica un database MySQL, PostgreSQL o genericamente collegato via ODBC, presente su altro server ldap : indica un'autenticazione mediante server LDAP come OpenLDAP o Active DIrectory soap : indica un'autenticazione mediante collegamento a WSDL SOAP. Questo tipo di autenticazione è sperimentale. Qualora si impostasse uno di questi parametri saranno richiesti altre variabili: $conf_auth['campo_email']='email'; // indica il nome del campo database o // LDAP per recuperare l'email dell'utente, // utilizzata per l'autenticazione 7

$conf_auth['campo_password']='passwd'; // indica il nome del campo database o // LDAP per recuperare la password dell'utente, // utilizzata per l'autenticazione $conf_auth['campo_nome']='nome'; // opzionale // Indica il nome del campo database o // LDAP da cui recuperare il nome dell'utente $conf_auth['campo_cognome']='cognome'; // opzionale // Indica il nome del campo database o // LDAP da cui recuperare il nome dell'utente $conf_auth['password_crypt']='md5'; // md5 sha1 null // Qualora le password fossero archiviate // come hash md5 o sha1 impostare questo parametro 5.2.1 Autenticazione mediante database presente sullo stesso server (solo MySQL) Qualora si sia scelta l'autenticazione esterna mediante DB diverso da VFront, impostare i seguenti parametri : $conf_auth['db']['database']='nome_database'; // deve risiedere sullo stesso server (Solo Mysql) // -- per altri server utilizzare DB_EXT, SOAP o altri metodi $conf_auth['db']['tabella']='nome_tabella'; // nome della tabella da interrogare per l'autenticazione 5.2.2 Autenticazione mediante database esterno e/o residente su altro server (MySQL, PostgreSQL, ODBC) Qualora si sia scelta l'autenticazione esterna mediante DB esterno e o residente su altro server, impostare i seguenti parametri 8

$conf_auth['db_ext']['dbtype']="mysql"; // Può essere "mysql" oppure "postgres" oppure genericamente "odbc" $conf_auth['db_ext']['host']="localhost"; // host del server DB esterno utilizzato per l'autenticazione $conf_auth['db_ext']['port']="3306"; // porta del server DB esterno utilizzato per l'autenticazione: // di default 3306 per MySQL e 5432 per PostgreSQL $conf_auth['db_ext']['user']="utente"; // utente per l'autenticazione $conf_auth['db_ext']['passw']="segreta"; // password $conf_auth['db_ext']['dbname']="vfront_test"; // nome del database $conf_auth['db_ext']['tabella']="utente"; // nome della tabella $conf_auth['db_ext']['odbc_dsn']=""; // solo per connessioni ODBC: scrivere il DSN 5.2.3 Autenticazione mediante LDAP o Active Directory Qualora si sia scelta l'autenticazione esterna mediante LDAP (o Active Directory) impostare i seguenti parametri : $conf_auth['ldap']['base_dn']='o=nome del server,c=it'; // DN completo del server LDAP $conf_auth['ldap']['host']='localhost'; // host del server LDAP 5.2.4 Autenticazione mediante SOAP (sperimentale) L'autenticazione SOAP è sperimentale e per ora si basa su le WSDL Qualora si sia scelta l'autenticazione esterna mediante SOAP impostare i seguenti parametri : $conf_auth['soap']['wsdl']=; // indirizzo http(s) del file WSDL $conf_auth['soap']['function_get_user']=; //nome di funzione per interrogare l'elenco degli utenti $conf_auth['soap']['function_get_user_results']=; // nome di funzione per recuperare i dati degli utenti 9

5.3 Sezione SMTP e e-mail VFront utilizza la classe PHPMailer per l'invio delle email. Per maggiori approfondimenti si veda http://phpmailer.sourceforge.net/ E' possibile con- gurare l'invio di email tramite SMTP mediante i seguenti parametri: $conf_mail['smtp_auth']=false; // indica se utilizzare un SMTP personalizzato. // In caso contrario verrà utilizzato l'smtp del server. // Le seguenti tre variabili sono da impostare // qualora l'autenticazione SMTP sia impostata su TRUE: $conf_mail['smtp']=""; // Indirizzo SMTP da utilizzare qualora si voglia fare uso // di STMP personalizzato $conf_mail['smtp_auth_user']=""; // utente smtp $conf_mail['smtp_auth_passw']=""; // password smtp $conf_mail['mail_sender']=""; // email del mittente per gli invii effettuati da VFront // (principalmente per il debug) // ad esempio "noreply@vfront.org" $conf_mail['mail_sender_name']=""; // Nome in chiaro del mittente per gli invii effettuati da VFront // ad esempio "Admin VFront" E' richiesto inoltre di impostare le costanti: // mail amministratore di sistema define('_sys_admin_mail','admin@vfront.org'); // mail dello sviluppatore (per le email di debug) define('_dev_mail','dev@vfront.org'); La mail dello sviluppatore può essere utile qualora si volesse far arrivare un debug allo sviluppatore. Le email vengono inviate qualora VFront generi un errore e il debug sia impostato su FALSE (si veda la sezione successiva). 5.4 Sezione Debug La sezione debug consta di tre variabili qui descritte: // errori a video errori in email $DEBUG_SQL=true; 10

In ambiente di produzione si consiglia di impostare la variabile su FALSE: in caso di errore verrà spedita una email all'amministratore ed allo sviluppatore. L'utente vedrà in questo caso una schermata dove si comunica che è stato generato un errore. In caso la variabile sia TRUE gli errori e l'sql verranno invece mostrati a video. $RPC_DEBUG=true; // scrivi le chiamate SQL in un file // (di default./rpc.debug.txt) - default: FALSE Questa funzione può essere molto utile per leggere cosa VFront ha eseguito mediante chiamate esterne. Il le./rpc.debug.txt deve essere scrivibile da Apache. 5.5 Sezione Log In questa sezione è presente una sola variabile che abilita o disabilita i log. Il log di VFront permette di registrare data, ora, e autore di tutte le operazioni compiute attraverso le maschere, mostra uno storico dei record e permette un rollback delle cancellazioni e delle modiche. Si consiglia caldamente di tenere il parametro impostato su TRUE. $RPC_LOG=true; // scrive un log delle chiamate SQL di inserimento, modifica e cancellazione // default: TRUE 5.6 Sezione localizzazione: lingua e codica In questa sezione sono impostate la lingua e la codica. Le lingue sono impostate in modalità language country come ad esempio en_us per la dicitura en. La traduzione del javascript avviene leggendo l'impostazione linguistica nelle sue due prime lettere (ad esempio per en_us verrà automaticamente letto 'en'). /** * Language : Valori possibili: it_it, en_us, fr_fr, etc. */ define('front_lang','en_us'); Per quanto riguarda la codica si suggerisce di mantenere l'utf-8: /** * Encoding */ define('front_encoding','utf-8'); 11

5.7 Sezione Path In questa sezione sono congurati gli indirizzi web e sul server di VFront: // path reale define('front_root','d:/htdocs/vfront_test'); // path reale define('front_realpath','d:/htdocs/vfront_test'); // Path della document root define('front_docroot','http://localhost/vfront_test'); // Nella maggior parte dei casi i seguenti si possono lasciare così come sono: // path mysqldump (per l'esportazione di MySQL) - Default: mysqldump define('_path_mysqldump',"mysqldump"); // path pg_dump (per l'esportazione di Postgres) - Default: pg_dump define('_path_pg_dump',"pg_dump"); // path per il filesystem allegati define('_path_attachment',front_realpath."/files"); // path di tmp per il filesystem allegati define('_path_attachment_tmp',front_realpath."/files/tmp"); // path per il filesystem documenti utili define('_path_helpdocs',front_realpath."/files/docs"); // path di tmp accessibile via web define('_path_tmp',front_realpath."/tmp"); // path per i fogli di stile XSL allegati define('_path_xsl',front_realpath."/files/xsl_custom"); // path web per i fogli di stile XSL allegati define('_path_web_xsl',front_docroot."/files/xsl_custom"); 5.8 Sezione FOP VFront utilizza Apache FOP ( http://xmlgraphics.apache.org/fop/ )per le trasformazioni XSL-FO e la generazione dei report in PDF. FOP non è distribuito insieme a VFront, ma va scaricato ed installato a parte. 12

// Imposta se VFront può utilizzare l'applicazione FOP (true o false) define('_fop_enabled',true); // Path di FOP sul server (esempi): //define('_path_fop','c:/fop-0.20.5/foptest/fop.bat'); //define('_path_fop','/usr/local/fop/fop.sh'); Il server Apache deve poter eseguire FOP perché le funzioni vengano eseguite correttamente. 5.9 Sezione Allegati e Link Ogni tabella del database su cui si sta eseguendo VFront può essere potenzialmente abilitata al supporto di allegati e link. I seguenti parametri solitamente sono funzionanti e si consiglia di modicarli solo qualora si utilizzassero altre tabelle per allegati e link. Si noti che in tal caso i nomi dei campi dovrebbero coincidere con quelli delle tabelle del database VFront. // definizione della tabella allegato define('_tabella_allegato',"{$db1['frontend']}.allegato"); // definizione della tabella link define('_tabella_link',"{$db1['frontend']}.link"); 5.10 Sezione Misc In questa sezione sono denite costanti di vario genere: define('_max_tempo_edit',240); VFront è pensato come front-end multiutente: per evitare accessi concorrenti in modica allo stesso record, c'è una procedura di "lock" del singolo record quando questo viene aperto in modica da un utente. Questa costante esprime in secondi il tempo massimo secondo il quale il record debba essere considerato bloccato (di default 240 secondi, cioè 4 minuti). define('_base64_passfrase',"passfrase"); In alcune operazioni viene utilizzata una codica in base64 di parametri negli URL. Questa costante imposta una frase per la codica. define('_img_logo',front_docroot.'/img/vfront090.jpg'); Indica il path del logo in alto a sinistra per le pagine di VFront define('_nome_proj','vfront'); Nome descrittivo dell'installazione di VFront (ad esempio "Front-end Biblioteca" o semplicemente "VFront") 13

5.11 Inclusione del le di congurazione Come ultima operazione di congurazione è necessario aprire il le inc/conn.php per scrivere il path reale del le di congurazione. ################################################ # COLLEGAMENTO AL FILE CONF # // ad esempio require_once("d:/htdocs/vfront_test/conf/conf.vfront.php"); // oppure require_once("/var/www/vfront/conf/conf.vfront.php"); 6 Procedura di installazione automatica VFront possiede un installer automatico. Prima di avviare la procedura, assicurarsi che il le conf.vfront.php sia stato correttamente congurato. La procedura di installazione si avvia direttamente da web mediante l'url: http://nome_del_server/path_vfront/_install/ La procedura richiederà 1. Il path del le di congurazione, che verrà letto per l'installazione 2. Un'autenticazione di alto livello sul database (root o simile) per creare le tabelle, l'utente specicato nel le CONF e i diritti a lui riservati 3. email e password per il primo utente (l'amministratore) Durante l'installazione è possibile dare un'occhiata alle query che si stanno per eseguire. Dopo l'installazione si consiglia caldamente di cancellare la cartella _install per ovvie ragioni di sicurezza. 7 Procedura di installazione manuale Qualora non si volesse o non si potesse lanciare la procedura di installazione automatica procedere come segue: 1. Assicurarsi che il le conf.vfront.php sia stato correttamente congurato 2. Modicare il le inc/conn.php per puntare correttamente al le di congurazione 3. Creare l'utente database specicato nel le conf e attribuire diritti d'uso (SELECT, DELETE,INSERT, UPDATE) nonché il diritto SHOW VIEW sul database che si vuole leggere con VFront 4. Attribuire i diritti d'uso sul database (o schema su Postgres) di VFront 14

5. Attribuire i diritti di lettura sull' information_schema se necessario 6. Eseguire sul server database i le _install/vfront.mysql.sql oppure _install/vfront.postgres.sql a seconda del DB che si vuole utilizzare 7. Creare un utente nella tabella "utente" del database (o schema) di VFront che abbia livello=3 e gruppo=0. Nota bene che la password deve essere espressa in hash md5. Per generare un hash md5 della tua password utilizzare md5 da shell (su Linux) oppure utilizzare uno dei tanti convertitori presenti su web, ad es. http://pajhome.org.uk/crypt/md5/ Dopo l'installazione si consiglia caldamente di cancellare la cartella _install per ovvie ragioni di sicurezza. 8 Dopo l'installazione 8.1 Inizializzazione del sistema Una volta eseguita l'installazione è necessario inizializzare il sistema. VFront deve leggere l'information schema e inserire le informazioni sul database che si sta leggendo nelle proprie tabelle. Per farlo 1. Fare login con il proprio account di amministratore 2. Accedere alla sezione amministrazione 3. Nel primo menu scegliere "Inizializza registri" Verrà avviata una procedura automatica che creerà le regole di base per la consultazione delle tabelle. Per la congurazione delle tabelle si rimanda al manuale di riferimento di VFront. 8.2 Test impostazioni VFront Per eettuare una diagnostica dell'installazione si suggerisce inne di accedere al menu di Amministrazione, sezione "Varie" ed eseguire il "Test impostazioni VFront". Per ulteriori informazioni su questa funzione si rimanda al manuale di riferimento di VFront. 15