Installation guide for Cross-Desktop on Unix based systems.

This installation guide addresses the Single-User-Version of Cross-Desktop.

Content

I.   Installation concepts
II.  Description of installation parameters
III. Installation of Cross-Desktop
IV.  Informationen for maintenance



I. Installation concepts

Cross-Desktop can be run by two installation concepts. These concepts differ in the way, that user data can be seen directly by the webserver or not. Which means user data could be directly accessed by an url that is not a Cross-Desktop url. On the other hand, user data can be configured to be stored outside the view of the webserver so cannot be accessed directly by an url that is not a Cross-Desktop url.

Concept 1: User data to be stored in the document root of the webserver

If Cross-Desktop is configured to have user data being stored in the document root of the webserver, it may be necessary to save user data for unsolicited access. Typically, webservers are configured using the .htaccess features in order to restrict access to certain directories or files. The installation program supports this feature with the option "Protection of the secure path" at the end of its configuration form. This part of the form should only be used if Cross-Desktop will be run by this installation concept.

Example:
Website: /home/www/website/html
Secure Path:/home/www/website/html/xddata/store
Protection of the secure path:
    Username: SiteAdmin
    Password: <secure-pwd>

Concept 2: User data to be stored outside the documemt root of the webserver

In order to savely store the user data on the server the data should be stored in a way that no webserver should be able to access the data via direct url. Many webserver configurations are setup on a base directory like /home/www. Undernease of this directory all websites are stored. The directory chosen for Cross-Desktop should not be part of /home/www.

Example:
User data base: /home/xddata
Secure Path:/home/xddata/store

In the following text any example uses path configurations following concept 2.


II. Description of installation parameters

Secure Path:
Path to store passwords and session data for a particular user. The directory will be created by the installation process if not already existing. If to be created the user running setup.cgi has to have write access to that directory. In this directory Cross-Desktop will later create a directory for any created user named by the user name. The user specific data will be stored in this directory. The directory will be created automatically by setup.cgi if the script is write enabled to do this.
Example: 
Concept 1: /home/www/website/html/xddata/store
Concept 2: /home/xddata/store

URL
URL to access the program files of Cross-Desktop. The webserver must be configured to execute cgi-scripts in this directory. The directory will be created automatically by setup.cgi if the script has write access to do this.
Example: http://www.website.de/cgi-bin/crossDesktop 

HTML URL
URL to access the Html and Javascript files of Cross-Desktop. The directory will be created automatically by setup.cgi if the script has write access to do this.
Example: http://www.website.de/crossDesktop/html 

Image URL
URL to access the image files of Cross-Desktop. The directory will be created automatically by setup.cgi if the script has write access to do this.
Example: http://www.website.de/crossDesktop/images 

Perl path
Path where the perl installation resides. Normally, /usr/bin/perl. The webspace documentation provided by your isp may help.

Zip path
Directory where to start the zip program. Normally, /usr/bin/zip. Some systems require to additionally install zip. Setup.cgi can consider this by the check box "Install zip later". The webspace documentation provided by your isp may help.

Unzip path
Directory where to start the unzip program. Normally, /usr/bin/unzip. Some systems require to additionally install zip. Setup.cgi can consider this by the check box "Install zip later". The webspace documentation provided by your isp may help.

Redirect
URL to redirect the browser to after logging off Cross-Desktop.
Example: http://www.website.de/

Session Timeout
Time for the runtime period of a user session. The time can be configured in the form 4h as for four hours or 3h4m30s as for three hours, four minutes, and 30 seconds. Only integer numbers are allowed for time specification.

Maximum Quota
Virtual memory limit in the Cross-Desktop to be managed. Provide numbers in KB, MB or GB. Only integer numbers are allowed to be specified.
Example: 100MB.

Showed basename
Synonym/name for the root directory to be displayed in the file explorer of Cross-Desktop.
Example: Start

Password for the default user
Password for the initial user. The password has to be provided twice.

Protection of the secure path
With respect to installation concept 1, this option result in the creation of a .htaccess file that will save user data in the case that user data will be stored in the root directory of the webserver. This option allows to specify dedicated access to the secure data area or enables to use an existing user list. In this case, the user list means to be system administrator users that will maintain the directory tree for this particular data area and will need web access to this data area. More information about .htaccss files can be obtained from the webserver documentation.

Username: name of the administrative user for this data area.
Password: password of the administrative user for this data area.
Passwordfile: (optional, for experts!) This option allows to use a existing password file for this issue. The parameters username and password are to be left empty.


III. Installation of Cross-Desktop

Prior the installation:
Before installation the detailed path information of the webserver have to be prepared. The information can be obtained from the documentation provided by your ISP. Mostly, the information can be found where cgi issues are described.

The installation script setup.cgi requires a directory on the webserver that is configured to execute cgi scripts. It is recommended to create a seperate directory for the setup script, i.e. cgi-bin/xdsetup.

When run, setup.cgi will ask for all the necessary parameters in order to install Html, program, and images files. In order to install the files setup.cgi requires write access to the specified installation directories.

Consider, the path to the root directory (/home/www/sites/myrootdir) of the webserver is the place where the respective domain (http://www.website.de/) awaits files like index.html.

Installation process:
1. Copy the installation script setup.cgi and the archive file files.tar.gz to the installation directory.

2. Change access rights of the files. setup.cgi requires 755 (chmod 755 setup.cgi) and files.tar.gz requires 666 (chmod 666 files.tar.gz).

3. Execute setup.cgi from within the browser: http://www.website.de/cgi-bin/xdsetup/setup.cgi

4. Follow the form based installation. Read II. for more installation about the installation parameters.

5. At this stage the installation should be already finished.

6. Should the installation not complete successfull, the browser's back button allows to step back. Missing access rights to files and directories can be configured manually and setup.cgi can continue in most cases. Missing directories can be created manually as well.

Potential problems
1. Access right problems: This is the case most happening during installation, especially if you are not experienced to install web applications. In order to run Cross-Desktop it is necessary that the webserver has read, write or execution rights in particular directories. For any domain configured in the webserver configuration script httpd.conf a particular user is assigned in who's name any scripts are run. Any files and directories to be access by a particular domain have to be assigned to this user. Is this not the case, you have to login to the server and correct file access rights with the command chown or call your administrator to do this for you. Directories and scripts generally are configured to 755. Any other files are configured to 666.

2. The installation directory does not allow to execute scripts: The webserver must be configured to execute scripts in the installation directory. In order to test whether scripts can be executed in the installation directory, just copy an existing script of which it is known to run into the installation directory. Call the script from within the browser with the respective url. In case the script is not been executed you will see the programming code of the script in your browser window.

There are various ways to configure scripts to be executed by the webserver. In one case you will have to add a comparable line into the configuration file of the webserver.
ScriptAlias /crossdesktop/ "/home/www/sites/myrootdir/cgi-bin/xdsetup"

With the above line the directory "/home/www/sites/myrootdir/cgi-bin/xdsetup" will be configured to execute scripts. Additionally, it is possible to call scripts in the following way:
http://www.website.de/crossdesktop/setup.cgi

3. Directories cannot be secured with .htaccess: The webserver needs to know where to search for .htaccess files. The following lines to be configured in the http.conf file tell the webserver that .htaccess files are configured and who will have access to the particular directories and files.
<Directory "/home/www/sites/myrootdir/crossdesktop/xddata">
    AllowOverride All
    Options ExecCGI
    Order allow,deny
    Allow from all
</Directory>


IV. Information for Maintenance

Maintaining Cross-Desktop by Cross-Desktop
With appropriate configuration of a Cross-Desktop user the complete website of the domain and Cross-Desktop itself can be maintained on file level by Cross-Desktop. In order to achieve this, an administrative user may be created in Cross-Desktop (Menu Applications/Administrator), i.e SiteAdmin. The working directory of user SiteAdmin is set to the root directory of the webserver (/home/www/sites/myrootdir). Logging in with user SiteAdmin the root directory of the particular domain will be the file space for SiteAdmin. Using the Cross-Desktop integrated text editor notepad scripts and html files can be edited online. Graphic and other binary files can be easily uploaded and downloaded. A symbolic link on the unix file system allow to link to the user files and user configuration data.
Attention! Any changes are of direct effect to the website. Links to the user data should be secured by .htaccess. 



Copyright 2004, Cross Development 