Physically, Application Vault is a connected structure consisting of database tables, files and directories.

The Application Vault root directory is located in <plesk_root_dir>/var/cgitory, where <plesk_root_dir> is the path in the file system to the directory where Plesk Server Administrator is installed. By default, for UNIX systems the path is as follows /usr/local/psa. For Windows systems it is as C:\Program Files\SWSoft\PSA. 

During its installation in the system, the application creates a subdirectory in the root directory of the repository. The subdirectory name is formed in the following way:

< application name >-< application version >-< application release>

Otherwise, the control panel won't find the directory of the newly installed application. Such mechanism of names creation makes it possible  to keep several versions of one application in the repository, if it is necessary (for example, a certain user prefers to use a certain version of the application).

The following system directories should be definitely located in the subdirectory:  

• scripts - the directory with the scripts for installation/configuration/upgrade/removal of applications on a domain;
• forms - the directory which contains data input forms for installation/configuration of applications on domains, and also handlers for these forms;
• apps - the directory for archives containing the main files of the application that will be unpacked on a domain;
• uninstall - the directory with the script for removing an application from the repository. This directory is only used for the applications, packed in the tar, sh archives. For RPM packages, this functionality is laid in the package itself (PREUN and POSTUN scripts); 
• docs - the directory containing online user documentation on the application;
• info - the directory with the xml-file, describing the application properties. It lists the requirements to the virtual host and the resources the application will use on the virtual host. Also, this directory contains the image used for creating an custom button;
• screenshots - the directory contains the illustrations of the application front end.
  

If it necessary for a web application to have system files outside of repository/virtual hosts directories (so'files, dll, language modules), these files may be installed during installation of the package in the system. It is done automatically for RPM packages. In other cases, the way of installation depends on the developer of the package. 

Scripts directory 

This directory is used for storing scripts (executable scenarios), which do low-level tasks at actions, performed on the application.  

The following scripts can be called in from the scripts directory of an application: 

• preinstall - called after parameters necessary for installing an application on a domain are received from a user, but before the application is unpacked in the domain. The script must check whether the system is compatible with the installed application and prepare the virtual host for installation. If the script returns a non-zero result, the installation of the application is aborted. 
• postinstall - called after the application is unpacked. This script is designed for altering the application unpacked on the virtual host, so that it could become functional. If the script returns a non-zero result, this result is sent to the user, but the application remains registered on the domain.
• reconfigure - called after new parameters of the application are received from the user. This script alters the application installed on the virtual host in accordance with new data received from the user. 
• preuninstall - called before the files of the application are removed from the virtual host.
• postuninstall - called after the files of the application are removed from the virtual host.
• preupgrade - called before the application is unpacked on the domain, in cases when the application is going to be installed on the old version.  If the script returns a non-zero result, the update of the application on a virtual host is aborted. 
• postupgrade - called after the package is unpacked in the virtual host over the old version of the application. 

These files can be both system supported scripts (such as shell or vbs, for example) and ordinary executable files. Names of installation scripts are given in the sapp_constants configuration file.

Scripts parameters are sent to the standard input in the form of a set of lines in the following format: 

< parameter name >=< parameter value >

Note: The equals sign must not be separated by blanks.

Here is the example of how to extract parameters from a standard input stream:     

#!/bin/sh>  # Read parameters from stdin FS_BACKUP=${FS} FS="\n" parameters=`cat`  for i in ${parameters}; do     eval $i || (echo "Error in parameters list ($i)" && exit 1) done || exit 1; FS=${FS_BACKUP}  # now we have full set of parameters, stored in variables

Note: You shouldn't forget that these scripts must be executed with the permissions of the user this virtual host belongs to. 

All the described scripts are optional and are used only when it is necessary to have corresponding functionalities for the application.

Forms directory

This directory contains files with HTML or PHP codes used when it is necessary to acquire a user about parameters of the application when installing, reconfiguring or updating it on the domain. The process of data input by the user may be a multi-step one, that is why when installing an application on the domain, for the files with the input elements forming code, names are formed in the following way:   

installer-form-<step number>.php

Also, this directory contains files with the code of processing the data received at every step (check that input data is correct, full and etc.). For the files with a data processing code, during the installation of the application on the domain, names are formed in the following way: 

installer-handler-<step number>.php

For the files with the data processing code, in the process of reconfiguration of the application on the domain, names are formed in the following way: 

reconfigure-handler-<step number>.php

For the files with the input elements forming code, in the process of reconfiguration of the application on the domain, names are formed in the following way: 

reconfigure-form-<step number>.php

If any of these files is missing in the directory, it is not considered to be an error. 

If at the first step of installation both files are missing (the file with the form forming code and the file with the data processing code), it means that the user is acquired only the name of the subdirectory in the virtual host, where the application should be unpacked, and in which part of the virtual host the application should be installed (SSL or non-SSL).  

If the files of the first step of reconfiguration are missing, it means that reconfiguration is impossible. 

If the files of the first step of updating are missing, it means that the application doesn't support its own updating mechanism and it should be updated in the standard way - by removing files of the old version and unpacking files of the new one.

Apps directory

This directory contains the archives with the application files used for installing it on the virtual host. At the present moment, there are two types of archives in this directory. They have the following functions:

- the httpdocs-files.tar archive contains information files of the application, designed to be unpacked in the http(s)doc directory of the host;

- the cgi-bin-files.tar archive contains application files with CGI-scenarios, designed to be unpacked in the cgi-bin directory of the host.

Both files are optional. If both files are missing, it may mean that either there is an error in the web application package, or the application will be formed by a postinstall script. 

Uninstall directory

This directory is used only for non-RPM packages. It contains the uninstall script, which has the functionality equal to the PREUN script in RPM packages. The control panel executes this script when an application is removed from the repository before removing the package directory in the repository. The functions of this script are fully described in the Removing Package From Repository section. 

Docs directory

This directory should contain the index.<locale name>.html file which has the user manual for this application. Locale name is the name of the locale this document is written in, which coincides with the locale used by a customer. The control panel searches for this file, and, if it is found, the link to this document is displayed in the list of all available or installed web applications. If the locale, used by the customer, does not coincide with the default locale name, the index.< default locale name >.html file is searched for, and, if it is found, the link to this file is given. Default locale name is the locale the package was originally created to be used in (for example, the native system of developers). In case neither of the previous variants was realized, the system searches for the file with the manual, created in the English (USA) locale ( en(US) ). More about locale names see here.       

Info directory

This directory contains the info.xml file which is used to describe the application properties, its system requirements and configuration parameters. The package must definitely contain the directory and the file, otherwise it won't be accessible from the control panel:

The info.xml file sample:

<?xml version="1.0" ?> <!-- $Id: ch05.html,v 1.4 2005/01/24 06:06:05 sshunin Exp $ --> <!DOCTYPE WEBAPP SYSTEM "WEBAPP 1.0"> <WEBAPP name="webExample" version="1.51" release="1" type="advanced_cgi"> <VERSIONHISTORY>     <VER value="1.51-1"/> </VERSIONHISTORY>  <ATTRIBUTES>     <DESCRIPTION>webExample is a test application  //short description of application     </DESCRIPTION>     <LICENSE accept_required="no" integrated="no">GPL</LICENSE> //license description     <ATTRIBUTE name="disc_space" value="795514" />  //needed disc space size </ATTRIBUTES>  <REQUIREMENTS>     <APACHE_VHOST name="PHP" value="on" /> //need installed PHP     <APACHE_VHOST name="cgi" value="on" />     <DATABASE type="mysql" name="" username="" passwd="" host="localhost" port="4564" />   // need installed MySQL database </REQUIREMENTS>  //configuration parameters <PROPERTIES>     <PROPERTY name="we_dbname" default="" type="string" />     <PROPERTY name="we_dbuser" default="" type="string" valtype="login" />     <PROPERTY name="we_dbpasswd" default="" type="string" valtype="password" />     <PROPERTY name="we_admin_email" default="" type="string" />     <PROPERTY name="we_admin_passwd" default="" type="string" valtype="password" />    </PROPERTIES>  <POSTCREATE> </POSTCREATE> </WEBAPP>

Also, it contains the button.gif file with the image for the custom button.  

Screenshots directory

This directory contains the app_screenshot_1.png and app_screenshot_thumb.png files with illustrations of the application front end. (Please, see <Example>).

Repository structure sample

The sample of the repository structure with the installed webexample-2.0.2-3 application:

/usr    /local       /psa          /var             /cgitory                /webexample-2.0.2-3                   /scripts                      postinstall                      postuninstall                   /forms                      installer-form-1.php                      installer-handler-1.php                      installer-form-2.php                      installer-handler-2.php                   /apps                      cgi-bin-files.tar                      httpdocs-files.tar                   /uninstall                      uninstall                   /docs