formVista™ Installation Guide
Installing formVista for the first time involves:
Use sftp, scp or your favorite method for transferring large files to your webserver to upload the formvista distribution. (e.g. formvista_0.8.9.0.tar.gz).
formVista must be installed under your "DOCUMENT_ROOT", the directory on the server from which your web pages are served. Under CentOS for instance, the default location for DOCUMENT_ROOT is /var/www/html. Some hosting providers put the DOCUMENT_ROOT under your login directory. Each host may be different. If you do not know where your document files are, please ask your administrator.
Typically formVista is installed in the top level document directory. (i.e. so that is is available from http://www.yourdomain.com/formvista), however formVista can be installed in a subdirectory.
To unpack the distribution first change into your DOCUMENT_ROOT directory:
$ cd WWW
where WWW is whatever your web pages directory is.
$ tar xzf formvista_0.8.9.0.tar.gz
This will create a directory called "formvista".
Change the ownership of the formvista files to match the user the web server is running as:
$ chown -R <apache_user> formvista
where <apache_user> is the user your web server runs as. For instance, under CentOS by default the user Apache runs as is "apache".
If you do not know the answer to this, setup will tell you and you can come back to this step.
Once the distribution file has been unpacked, load the formVista setup program using your webbrowser by loading the page:
http://yourdomain.com/formvista/setup.php
where yourdomain is the domain name of your website. If you have installed formvista lower in the subdirectory tree on your website add the appropriate path.
As a first step, setup will create a "setup_password.php" file in the formvista directory and display a message "EDIT BEFORE USING". If you get a permission denied error here, it means the setup program does not have permissions to create files in the formvista directory and you will have to fix that before proceeding.
In your shell session, open the newly create setup_password.php file in a text editor and change the string "replace_with_new_password" with a password of your choosing. You will need to enter the password you choose here into the setup program to continue. You can also pull down the setup_password.php file and edit it locally and re-upload it.
Note: setup has been designed to be rerun as many times as you like. You can safely reload any page and safely go back page and retry them.
Reload the page in your web browser and you should now see a password login prompt.
Enter the password you selected and click Login.
Security Note:When you are finished with configurating the software you should remove the setup_password.php file.
The next screen is the license agreement. If you agree with our terms, select Yes and click next.
The next screen allows you to test your Apache setup. It also displays the user that the webserver is running as. If you have not already done so, go back to the Permissions section above and run the chown command to make sure all of your formvista files have the correct ownership.
You can now test your Apache web server setup.
Click on the Test Apache .htaccess link. You should see a new browser window displaying a prominent "FORBIDDEN" error message. If you do not, please review your Apache .htaccess file configuration or contact your web master. Close the window.
Next click on the Test Apache mod_rewrite link. You should see a new window with a one line message "rewrite works". If you do not, please review your Apache mod_rewrite configuration. Close the window.
Click Next.
The next screen checks various aspects of your PHP configuration including the list of required extensions.
It also checks that various formVista directories have the correct permissions.
During this step the "site_local" directory is created. This directory contains various files that are specific to your website.
Note: If a web designer has created a custom theme for you, it can now be unpacked into the formvista/site_local/themes/<theme_name> directory using your shell login. <theme_name> should be the name of the theme.
Click Next.
formVista requires the use of a MySQL database. In order to access that database, formVista needs to know what host the database server is running on, which is usually localhost. It also needs to know what user and password it should use to connect to the database with.
You may enter the name of an existing database or a new one. If the database name you select does not exist, setup will attempt to create it assuming that the MySQL user you selected has sufficient permissions to create a database.
Security Note: The MySQL password you select is stored encrypted.
The most common error is that the select MySQL user does not have sufficient permissions to create a database. For the security conscious we recommend:
There are some additional fields that need to be set:
Note: If the email notifications field is not properly set, you will not receive an email when someone tries to contact you through the website. If the php path is not correctly set, cronjobs such as the daily digest generator for the forum will not work.
Click next.
The next screen will list the configuration files and database tables as they are generated.
Note: If you are upgrading from a previous version, you may be prompted to click Next to upgrade the database schema to a new version.
formVista comes with a number of pre-installed themes that can be used for your front-end content managed website. Select a theme. If you have uploaded any custom themes created by a web designer, they will appear in the bottom section under Local Themes.
Click next.
Front end websites can be assembled from scratch but the myriad of different ways this can be done can be a but daunting for the first time user. To make it easier to get started, 5 "placeholder" sites that are ready to use "out of the box" are included. These sites include a single published page indicating the site is under construction and a set of unpublished pages. The pages include placeholder content that explains how to go about customizing your site content for your own use.
Using the backend content manager, you can start with any site type and create the others or mix and match. These site types simply represent typical starting points.
For advanced users, blank option is included.
From this screen you must also select an email address and password for logging into the administrative backend.
Separately, if you have selected one of the membership site options, you need to select an email address and password to use to log into the front end in addition to a front end username. In formVista logins to the front end and backend are completely separate.
Click Next.
If everything worked correctly, a confirmation screen is displayed indicating the site has been generated.
Click Next
formVista includes an extension system where new features can be added. These extensions reside under formvista/extensions and are separately installed.
A list of installed extensions is displayed. Two example extensions are included for developers as a reference.
Select any extensions you would like to enable. If you select any you will go through a set of extension specific screens that are beyond the scope of this document. Refer to the installation instructions that come with the extensions.
Click Next
In order for the content manager to work, a .htaccess file needs to be installed in the DOCUMENT_ROOT. If you already have a .htaccess file, you have the opportunity here to make a backup before installing the new one.
If you do not install the .htaccess file the icms content manager will not function.
Note: For advanced users, you can take a look at the formvista/etc/htaccess.dist file and merge the mod_rewrite rules with your own .htaccess file.
Click Next
Some extra features of formVista require that background processes, also called cronjobs, be run at regular intervals. For instance, if you want daily digest emails to be sent to all of your forum users, you will want to run the 'forumsNotifier' which actually sends out the emails.
A cronjob is a program run by the "cron" process on a Unix/Linux machine. When to run which program is determined by the cron table.
The programs intended to be run as cronjobs are located in the formvista/crontabs directory. The cronjobs there are:
To enable these cronjobs to be run from cron at regular intervals you must use the "contab -e" command to enter cronjob entries.
See the documentation for crontab.
For example to run the forumsNotifier at 3:30AM every day you would add a line like the following to your crontab using the crontab -e command:
30 3 * * * path/formvista/cronjobs/forumsNotifier/forumsNotifier.php > path /formvista/site_local/var/logs/forumNotifier.log.php
Where path is the path on the server to your formvista installation. We recommend redirecting the output of the cronjobs to the var/logs directory as they do generate output.