Manual installation guide

From VFront Wiki

Jump to: navigation, search

You are reading the english version English us.gif of the document.
La versione italiana รจ Italian.gif Guida all'installazione manuale

Contents

License of this document

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 ". 

Introduction Installation Manual

VFront is designed to be installed automatically. Open the URL in the browser where you unzipped the installer and part VFront driven. We suggest using this procedure.

However, it is possible that

This guide will show you how to install (and uninstall) VFront manually. It will show what is in the configuration file and how to change it knowingly.

Basic Requirements

VFront requires the following software:

It is better to use PHP as an Apache module. However is possible to use VFront with PHP in CGI mode, but may be encountered unexpected behavior.

Requires the following modules for PHP:

Optionally also require the following modules

For the operations relating to the reporting it is necessary to put allow_url_fopen parameter in option TRUE. Parameter can be set in php.ini or in httpd.conf (not eg in a. Htaccess). Instead, the statistics section uses PEAR (http://pear.php.net/) for the generation of graphs. Are therefore required, as well as PEAR packages:

Note: at the moment the package Image_Graph is at the release 0.72. This release has a small bug in the generation of the labels of pie charts, which are not shown without generating any errors. To solve the problem use the CVS version of the file Image / Graph / Plot / Pie.php recoverable from the address http://cvs.php.net/viewcvs.cgi/pear/Image_Graph/Graph/Plot/Pie.php


Important note for users of MySQL

VFront use the information_schema to retrieve information on the DB. It is clear that the MySQL INFORMATION_SCHEMA, being a logical view of all databases, has not good performance. If you use a MySQL database server with many (> ~ 100) databases and tables you may have a slowdown even on VFront (http://bugs.mysql.com/bug.php?id=19588). This tends to happen only in the procedures for administration.

The efforts, in the last days, are for a new version of VFront which will ignore the information_schema and will only use the functions on the structure (SHOW, DESCRIBE, etc.).


Important note for users of PostgreSQL

VFront makes great use of the views of the schema "INFORMATION_SCHEMA". There are some views that have the bug regarding the allocation of rights, errors documented on the forum site Postgres (read such http://archives.postgresql.org/pgsql-bugs/2006-12/msg00168. php and http://archives.postgresql.org/pgsql-hackers/2007-08/msg00329.php). The views involved are key_column_usage and table_contraints. These bugs have been dragged into several versions of Postgres from 7.4 (which you added the information_schema) to 8.2. The consequence of having "buggy" Postgres on VFront is the inability to detect the presence of primary keys and foreign keys in tables, compromising the functioning of the entire application.The problem does not occur in case of using a user "superuser as VFront user to read the database, however, choose not recommended for security reasons.To fix the bug, you can run the script in the folder named _install _install/postgres.information_schema.bugfix.sqlsuperadmin as a user (eg. "postgres"). The script (which recreates the sights with the appropriate attribution of rights) certainly works in version 8.1. For other versions you may need to make some changes to the bugfix.

Installation Procedure Manual

It will be shown here how to manually install VFront:

  1. Recover files and create the filesystem
  2. Creating database
  3. [[#Set_database_privileges|]Set database privileges|]
  4. Edit the file conf

Recover files and create the filesystem

You can recover files from sourceforge VFront in two ways:

From the official repository

https://sourceforge.net/projects/vfront/

Via SVN

The syntax is:

svn co https://vfront.svn.sourceforge.net/svnroot/vfront vfront

Download VFront in a directory subject to browsing by Apache or create an alias if we want to position in a special directory.

SVN Notes

The version of SVN is a development version, then there are bug fixes and new features long before the official versions. On the other hand it is also possible that there are not fully developed functions and files in alpha stage.

Creating database

VFront uses its own database (in PostgreSQL, more correctly, a schema) to handle forms and rules. As specified in Reference manual that database does not interact ,in any way, with the data in your database.

To create the database run the script in the folder _install with administrative privileges:

MySQL

_install/vfront.mysql.sql

PostgreSQL

_install/vfront.postgres.sql


Elimination of the temp group

The script above as well as create tables, it populates some (variable and group). To proceed with manual installation you must delete the group with

gid = -1

This is a temporary group, useful for automatic installation. If you proceed with the manual installation is important to delete this group.

Creating user admin

At this point, you must create the admin user. To do so create a user in the table "user" of the database (or schema) of Vfront having level = 3 and group = 0. Please note that the password must be expressed in md5 hash. If you work with phpMyAdmin, you have the option of converting into a MD5 string. Otherwise generate a md5 hash of your password, you can use md5 shell (on Linux), or you can use one of the many converters found on the web, eg. http://pajhome.org.uk/crypt/md5/

Set database privileges

Now should be granted the database rights to the user database that you intend to use.

Set Data database privileges

As for the data database (your database) the minimum rights set are:

MySQL:

SELECT, INSERT, UPDATE, DELETE, SHOW VIEW


PostgreSQL

SELECT, INSERT, UPDATE, DELETE, REFERENCES

Set VFront database privileges

Regarding the VFront database (or schema in Postgres) rights are:

SELECT, INSERT, UPDATE, DELETE





Edit the file conf

Folder conf file is present conf.vfront.php.dist

You have to do a copy and rename conf.vfront.php. You could always rename the original fileconf.vfront.php.dist but it is suggested to keep a copy if I wanted to reinstall VFront and use the automatic procedure.

You can also give it a different name and / or keep it in a different location in the filesystem. In this case you have to make some more changes documented in the Inclusion of configuration files

Copying files and setting the rights to files and folders

Unpack the archive in the directory VFront subjected to browsing.The directory structure should look like this:



VFRONT_ROOT
- _install
- admin
- conf
- files
   -- docs
   -- docsadmin
   -- html
   -- tmp
   -- xls_custom

- img
- inc
- js
- local
- plugins
   -- FCKeditor
   -- highlight
   -- phpmailer
   -- phpgettext
   -- ods
   -- phpExcelReader
   -- ttf
- stats
- sty
- themes
- usr
- xml


Some folders must be writable by Apache. These are:

If you wish to use the debug through the file rpc.debug.txt (see below for a description) this file should be writable by Apache.

The configuration file in detail

File's configuration name is conf/conf.vfront.php Through the configuration file you can set most parameters VFront. Other parameters relating to the use and appearance will be set by the area of administration and configuration of the variables of the table "variable".

Database connection

The first section of the configuration file is on the database connection. VFront can choose whether to use as a front-end for a MySQL 5.x, or PostgreSQL 8.x. Please note that while support for MySQL 5.x has had numerous tests and real applications, support for PostgreSQL is at present still be considered unstable and alpha stage.The parameters required are:

$db1['dbtype'] = "mysql"; 
// Indicates the type of database: can be "mysql" or "postgres". MUST be specified

$db1['host'] = "localhost";
// Host server 

$db1['port'] = "3306";
// Server port: default 3306 to 5432 for MySQL PosgreSQL

$db1['user'] = "username";
// User for the database connection

$db1['passw'] = "secret";
// Password to connect to the database

$db1['dbname'] = "bank";
// Name of the database: for postgres using "public", ie the schema name

$db1['frontend'] = "vfront_test";
// Database name VFront. In postgres match the schema name (it suggests "frontend" or "vfront")

$db1['postgres_dbname'] = "database_name";
// Real name of the database (only if you use Postgres) 

Authentication Settings

VFront allows authentication through its table "user" or by another system. The logic of authentication and user rights to accreditation are in fact disjoint.When you proceed with an external authentication (eg via LDAP) ,if the user exist, he is automatically authenticated on VFront there. The next step will be the accreditation of law through the user table: if the user does not exist on LDAP and the user table will be automatically entered in this, and will be awarded the rights by default (group 0). For more information on groups and user rights, see the documentation of VFront.The parameter for authentication is

$conf_auth['tipo_external_auth'] =''; 

If set =or = null authentication will be done through the database VFront and its user table.The other parameters are possible at

If you set one of these parameters will be required variables:

$conf_auth['campo_email'] = 'email';

// Indicates the field name database or LDAP to retrieve the user's email

// Used for authentication
$ conf_auth ['campo_password'] = 'passwd';

// Indicates the field name database or LDAP to retrieve the user password,

// Used for authentication
$ conf_auth ['campo_nome'] = 'name', / / optional

// Tell the name of the database field or LDAP to retrieve user name
$ conf_auth ['campo_cognome'] = 'Last Name', / / optional

// Tell the name of the database field or LDAP to retrieve user name

$conf_auth ['password_crypt'] = 'md5', / / md5 | sha1 | null 
// If the passwords were stored as md5 or sha1 hash set this parameter


Authentication using this database on the same server (only MySQL)

If it is chosen by DB external authentication other VFront, set the following parameters:


$ conf_auth [ 'db'] [ 'database'] = 'database_name'; 
// Must reside on the same server (only MySQL) - to other servers using DB_EXT, SOAP or other methods

$ conf_auth [ 'db'] [ 'table'] = 'table_name';
// Table name to be queried for authentication 

Authentication using external database and / or resident on another server (MySQL, PostgreSQL, ODBC)

If it is chosen external authentication through external DB and | or resident on another server, set the following parameters



$ conf_auth ['db_ext']['dbtype'] = "mysql"; 
// Can be "mysql" or "postgres" or generically "odbc"

$ conf_auth ['db_ext']['host'] = "localhost"; 
// External DB server host used for authentication 

$conf_auth['db_ext'][ 'port'] = "3306"; 
// External DB server port used for authentication: 
// Default 3306 to 5432 for MySQL and PostgreSQL

$conf_auth['db_ext']['user'] = "john"; 
// User authentication 

$conf_auth['db_ext']['passw'] = "secret"; 
// Password

$conf_auth['db_ext']['dbname'] = "my_wonderful_db"; 
// Database name

$conf_auth['db_ext']['table'] = "user_table"; 
// Table name

$conf_auth['db_ext']['odbc_dsn']=""; 
// Only for ODBC connections: to write the DSN 


Authentication via LDAP or Active Directory

If it is chosen through external authentication (LDAP or Active Directory) to set the following parameters:



/ * SECTION (LDAP or Active Directory) * /

// Base dn
$conf_auth['ldap']['base_dn'] = 'o = Server Name, c = U.S.';

// Host
$conf_auth['ldap']['host'] = 'localhost';

// Port by default is 389 on OpenLDAP, Active Directory 445
$conf_auth['ldap']['port'] = '389 ';

// Authentication (bind) anonymous
$conf_auth['ldap']['anonymus_bind'] = 1;

// Authentication (bind) with name and password
$conf_auth['ldap']['bind_user'] = 'someuser';
$conf_auth['ldap']['bind_passw'] = 'somepassword';




Authentication using SOAP (experimental)

Authentication SOAP is experimental and for now is based on WSDL fileIf it is chosen external authentication using SOAP set the following parameters:



// Http (s) of the WSDL file
$conf_auth['soap'][ 'wsdl']='';

// function name to query the list of users
$conf_auth['soap'][ 'function_get_user']='';

// Function name to retrieve user data 
$conf_auth['soap'][ 'function_get_user_results']='';

Section SMTP and e-mail

VFront uses the class PHPMailer for sending emails. For more insights seehttp://phpmailer.sourceforge.net/'Can be configured to send email via SMTP using the following parameters:



$conf_mail['SMTP_AUTH'] = false;

// Indicates whether to use a custom SMTP. Otherwise you will use the SMTP server.
// The following three variables are set if SMTP authentication is set to TRUE:

// SMTP address to use when you want to use custom STMP
$conf_mail['SMTP']="";

// SMTP user
$conf_mail['SMTP_AUTH_USER']="";

// SMTP password
$conf_mail['SMTP_AUTH_PASSW']="";

// Email of the sender to the letters sent by VFront (mainly for debugging)
// Example: "noreply@vfront.org"
$conf_mail['MAIL_SENDER']="";

// Name of the sender to clarify the letters sent by VFront
// Example: "Admin VFront" 
$conf_mail['MAIL_SENDER_NAME']="";


It 'also required to set the constants:


// Mail system administrator
define ('_SYS_ADMIN_MAIL', 'admin@vfront.org');

// Mail the developer (for the email debug)
define ('_DEV_MAIL', 'dev@vfront.org'); 

The e-mail the developer can be useful if you wanted to send a debug developer. Emails are sent when VFront generates an error and debug is set to FALSE (see next section)

Debugging

Debug section consists of three variables described above:


// Error in video | mistakes in email
$ DEBUG_SQL = true;


In production environment you should set the variable to FALSE: In case of error will be sent an email to the administrator and developer. The user will see in this case a screen where it said that it was an error.If the variable is TRUE and SQL errors will be displayed on screen instead.

// Write the SQL calls into a file (default. / Rpc.debug.txt) - default: FALSE 
$ RPC_DEBUG = true;


This feature can be very useful to read what VFront performed by external calls. The file. / Rpc.debug.txt must be writable by Apache.

Log Section

This section is only one variable that enables or disables the log.The log VFront lets you record the date, time and author of all transactions performed through the masks, shows a historical record, and allows for the cancellation and rollback changes. It is advised that you take the parameter set to TRUE.

// Write a log of SQL calls to insert, modify and delete - default: TRUE 
$ RPC_LOG = true;


Section localization: language and encoding

In this section you set the language and encoding. The languages are set to "country language" such as en_US for the words "en". The translation is done by reading the setting of JavaScript language in its first two letters (for example, en_US is automatically read 'en').


/**
* Language: Possible values: en_GB, en_US, fr_FR, etc..
*/ 
define ( 'FRONT_LANG', 'en_US'); 

As for the encoding is suggested to maintain the UTF-8:

/**
* Encoding 
* /
define ( 'FRONT_ENCODING', 'UTF-8'); 

Section Path

In this section are configured on the server and the web addresses of VFront:


/* FILESYSTEMS PATHS */

/**
  * Real path
  */
define('FRONT_ROOT', '/var/www/vfront');


/**
  * Real path
  */
define('FRONT_REALPATH', '/var/www/vfront');

/**
  * Path of document root: Insert here the path to the document root
  */
define('FRONT_DOCROOT', 'http://localhost/vfront');


Following are the other path. It is suggested to keep the settings as default. By default all files uploaded by users go to /files or in a subfolder. It therefore requires that its files and subfolders are accessible for reading and writing user Apache.



/* OTHER PATHS */

/**
  * Path mysqldump (for export to MySQL) - Default: mysqldump
  */
define ('_PATH_MYSQLDUMP', "mysqldump");

/**
  Pg_dump * path (for export to Postgres) - Default: pg_dump
  */
define ('_PATH_PG_DUMP', "pg_dump");
/ **

  * Path to the filesystem attachments
  */
define ('_PATH_ATTACHMENT', FRONT_REALPATH."/files");

/**
  * Path to the tmp filesystem attachments
  */
define ('_PATH_ATTACHMENT_TMP', FRONT_REALPATH."/files/tmp");

/**
  * Path to the file system useful documents
  */
define ('_PATH_HELPDOCS', FRONT_REALPATH."/files/docs");
/ **

  * Path to the file system useful documents
  */
define ('_PATH_HELPDOCS2', FRONT_REALPATH."/files/docsadmin");

/**
  * Path of tmp accessible via web
  */
define ('_PATH_TMP', FRONT_REALPATH."/files/tmp");
/**

  * Path to the XSL attachments
  */
define ('_PATH_XSL', FRONT_REALPATH."/files/xsl_custom");

/**
  * Web path to XSL attachments
  */
define ('_PATH_WEB_XSL', FRONT_DOCROOT."/files/xsl_custom");

Section FOP

VFront using Apache FOP (http://xmlgraphics.apache.org/fop/) for processing XSL-FO and generating reports in PDF.FOP is distributed with VFront, but must be downloaded and installed separately.


// Set if VFront can use the application FOP (true or false)
define ('_FOP_ENABLED', true);

// Path of FOP on the server:
// define ( '_PATH_FOP', 'C:/fop-0.20.5/foptest/fop.bat');
// define ( '_PATH_FOP', '/usr/local/fop/fop.sh'); 


The Apache server must be able to run FOP because the functions are performed properly.

Attachments and Links section

Each table in the database on which you are VFront can potentially be enabled to support attachments and links.The following parameters are functioning normally and you should change them only if you use any other tables for attachments and links.Note that in this case the field names should coincide with those of database tables VFront.

// Definition of the table annexed
define ( '_TABELLA_ALLEGATO',"{$ db1 [' frontend ']). allegato ");

// Table definition links
define ( '_TABELLA_LINK',"{$ db1 [' frontend ']). link "); 

Section Misc

In this section are defined constants of various kinds:


define ('_MAX_TEMPO_EDIT', 240);

VFront is designed as a front-end multi-user: To prevent concurrent access to edit the same record, there is a procedure to "lock" the individual records when you open it in edit by a user. This constant expresses in seconds the maximum time according to which the record should be considered blocked (default 240 seconds, ie 4 minutes).



define ('_BASE64_PASSFRASE', "passphrase");


In some operations it uses a base64 encoding of the parameters in the URL. This constant sets a sentence for the encoding.


define ( '_NOME_PROJ', 'VFront');

Installing VFront descriptive name (eg "Front-end Library" or simply "VFront"). This name will be used in the TITLE of the pages, but also as a session variable (cookie) for authentication.

Inclusion of configuration files

The configuration file that we have changed so far is included in all scripts from inc/conn.php

In the file inc / conn.php is arranged to include the file conf.vfront.php in its original position. If your configuration file had a different name, or was in a different location, then you change something even conn.php file, otherwise leave everything as is.

If you want to customize the file name or its location, file inc.conn.php change the opening lines:


###################################################
#
# Link to CONF FILE
#

$CONF_FILE = 'conf.vfront.php';



#########################
#
# Do not change from here ...
#


// Linux or Windows?
$dir_vfront = (substr (realpath (__FILE__), 0.1 )=='/')

         ? str_replace ( "/ inc / conn.php ",'', realpath (__FILE__))
         : Str_replace ( "\ \ inc \ conn.php ",'', realpath (__FILE__));

$POSIZIONE_FILE_CONFIGURAZIONE = $dir_vfront. '/conf/'.$ CONF_FILE;

After installation

System initialization

Once you install you must initialize the system. VFront must read the information schema and enter information on the database you are reading in their own tables. To do

  1. Log in with your administrator account
  2. Access the Administration section
  3. In the first menu, choose "Erase records"

This will start an automated process which will lay the ground rules for consultation of the tables.For the configuration of the tables, see the Reference Manual of VFront.

Test settings VFront

It is also suggested to access the administration menu, under "Miscellaneous" and run the "Test settings VFront.For more information, see the Reference Manual for VFront.

Uninstalling VFront

We propose two methods:

  1. Manual method
  2. Script in bash

Uninstalling: manual method

To uninstall VFront you do the following:

  1. On MySQL delete the DB frontend, or if you're using Postgres, the frontend schema (see the name specified in the configuration file).
  2. Delete the contents of subfolders of files
  3. Delete the file conf/conf.vfront.php

To eliminate completely VFront from your system, instead

  1. On MySQL delete the DB frontend, or if you're using Postgres, the frontend schema (see the name specified in the configuration file).
  2. Delete the entire folder VFront.

Uninstalling: Script in bash



#!/bin/sh

#########################################
#
#	VFRONT Uninstall script - MySQL Version
#


echo "--------------------------------------------"
echo "	VFront Unistaller 0.1		"
echo "--------------------------------------------"
echo ""


ROWFRONTEND=`grep "^$db1.*frontend.*=" ./conf/conf.vfront.php` 
ROWTYPE=`grep "^$db1.*dbtype.*=" ./conf/conf.vfront.php` 
ROWPORT=`grep "^$db1.*port.*=" ./conf/conf.vfront.php` 
ROWHOST=`grep "^$db1.*host.*=" ./conf/conf.vfront.php` 

DBFRONTNAME=`expr "$ROWFRONTEND" : '\$\db1\['"'"'frontend'"'"'\]="\(.*\)" *;' `
DBTYPE=`expr "$ROWTYPE" : '\$\db1\['"'"'dbtype'"'"'\]="\(.*\)" *;' `
DBPORT=`expr "$ROWPORT" : '\$\db1\['"'"'port'"'"'\]="\(.*\)" *;' `
DBHOST=`expr "$ROWHOST" : '\$\db1\['"'"'host'"'"'\]="\(.*\)" *;' `

echo "--------------------------------------------"
echo "	Finded this DB Vars: "
echo "	DB Type: $DBTYPE "
echo "	DB Host: $DBHOST "
echo "	DB Frontend: $DBFRONTNAME "
echo "	DB Port: $DBPORT "

if [ $DBTYPE = 'postgres' ] ; then
	
	ROWPG=`grep "^$db1.*postgres_dbname.*=" ./conf/conf.vfront.php` 
	DBPG=`expr $ROWPG : '\$\db1\['"'"'postgres_dbname'"'"'\]="\(.*\)";' `
	
	echo "	DB Name: $DBPG "
	
fi

echo "--------------------------------------------"
echo ""
echo ""


if [ $DBFRONTNAME = '' ] 
	then 
		echo "--------------------------------------------"
		echo "	Unable to delete database	"
else
	echo "--------------------------------------------"
	

	echo "	Deleting configuration file "

	#rm -f ./conf/conf.vfront.php

	echo "	Deleting temp and project files "


	rm -f ./files/docs/*
	rm -f ./files/docsadmin/*
	rm -f ./files/tmp/*
	rm -f ./files/xsl_custom/*
	rm -f ./files/html/*
	rm -f /tmp/tmp.sql

	echo "	Deleting database $DBFRONTNAME (if exists) "
	
	
	if [ $DBTYPE = 'mysql' ] ; then 
	
		echo ""
		echo "	MySQL db selected"
		echo ""
		
		echo "DROP DATABASE IF EXISTS $DBFRONTNAME ;" > /tmp/tmp.sql
	
		echo `mysql -h $DBHOST -P $DBPORT -uroot -p < /tmp/tmp.sql`
		
		rm -f /tmp/tmp.sql
		
	elif [ $DBTYPE = 'postgres' ] ; then
		
		echo ""
		echo "	PostgreSQL db selected"
		echo ""
		
		echo "DROP SCHEMA $DBFRONTNAME CASCADE ;" > /tmp/tmp.sql
		
		echo `psql -h $DBHOST -U postgres -p $DBPORT -d $DBPG -W < /tmp/tmp.sql`
		
		rm -f /tmp/tmp.sql
		
	else 
		echo "	Unable to select database type	"
	fi
fi

echo "	Execution done	"



Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox
Google AdSense