Difference between revisions of "WebIssues/Installation"

From MiMec
Jump to: navigation, search
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
This is the installation guide for WebIssues Server version 1.0.
+
This page contains platform specific installation notes for WebIssues Server 1.1. For general information about installing the server, refer to the WebIssues manual.
  
The installation guide for version 0.8.5 is available in the [http://doc.mimec.org/webissues/server/installation.html online manual] or in your local copy of the manual.
+
== Database ==
 +
 
 +
You can use an existing database instead of creating a new one. Just ensure that the tables used by the WebIssues Server have a unique prefix to avoid clashes with other tables. This way you can also install multiple instances of the server sharing a single database. It is also possible to create multiple instances of the server within a single installation (see [[../Configuration#Multiple_Sites|Multiple Sites]] for more information).
 +
 
 +
The database user used by the WebIssues Server to login to the database must have sufficient privileges to create tables. The simplest solution for MySQL is to grant ALL PRIVILEGES to the database; for SQL Server assign the user to the database owner role. Refer to the database documentation for more information about privileges.
 +
 
 +
In version 1.1 you don't have to edit the configuration file manually because the setup script will create it for you. If you want to change the connection options later, either modify the configuration file or delete it and run the setup script again. For security reasons it is not possible to run the setup script if the configuration file exists.
 +
 
 +
The following information can be used to set up the database using command line tools.
 +
 
 +
=== MySQL ===
 +
 
 +
1. Create the database (dbauser is the login of the database administrator, database is the name of the database to create):
 +
 
 +
mysqladmin -u dbauser -p create database
 +
 
 +
You will be prompted for the database administrator's password.
 +
 
 +
2. Connect to the database server:
 +
 
 +
mysql -u dbauser -p
 +
 
 +
From the MySQL command prompt execute the following query to create a user with access to the database (user is the user's login, password is the user's password and database is the name of the database):
 +
 
 +
GRANT ALL PRIVILEGES ON database.* TO 'user'@'localhost' IDENTIFIED BY 'password';
 +
 
 +
3. Execute the following query to activate the new permissions:
 +
 
 +
FLUSH PRIVILEGES;
 +
 
 +
=== PostgreSQL ===
 +
 
 +
1. Create the user account (user is the user's login):
 +
 
 +
createuser --pwprompt --encrypted --no-adduser --no-createdb user
 +
 
 +
You will be prompted for the password for the new user. Note that you have to log in as a user with appropriate permissions to manage the PostgreSQL server.
 +
 
 +
2. Create the database (user is the user's login, database is the name of the database to create):
 +
 
 +
createdb --encoding=UNICODE --owner=user database
 +
 
 +
=== SQL Server ===
 +
 
 +
1. Connect to the database server:
 +
 
 +
sqlcmd.exe -U dbauser -P dbapassword
  
Note that the alpha development version should be used for testing purposes only. It is not possible to update and older version to an alpha version and it will not be possible to update the alpha version to a later version. Also the alpha version of the server is only compatible with the same version of the desktop client.
+
Replace dbauser and dbapassword with the login and password of the database administrator.
  
== Requirements ==
+
2. Execute the following queries to create a user's login and the database (user is the user's login, password is the user's password and database is the name of the database to create):
  
* Web server with PHP version 5.2.1 or newer (http://php.net/)
+
CREATE LOGIN user WITH PASSWORD = 'password';
* The following PHP extensions:
+
GO
** mbstring (required)
+
CREATE DATABASE database;
** mysqli (required when using MySQL database)
+
GO
* One of the following database servers:
 
** MySQL version 4.1 or newer
 
** SQL Server 2005 or newer (supported on Windows only)
 
  
The system is being tested with Apache and IIS servers. Other web servers may also work, but are not officially supported.
+
3. Execute the following queries to assign appropriate permissions for the database to the user (user is the user's login, database is the name of the database):
  
== Quick Steps ==
+
USE database;
 +
GO
 +
EXEC sp_grantdbaccess 'user';
 +
GO
 +
EXEC sp_addrolemember 'db_owner', 'user';
 +
GO
  
# Unpack the entire WebIssues Server package to the web server's document root directory.
+
== Web Server ==
# Create a database and a user account with sufficient privileges to create tables in that database.
 
# Make sure that the data/ subdirectory is writable for the web server.
 
# Point your browser to the admin/setup/install.php page and follow the instructions.
 
  
== Database ==
+
Copy the contents of the server installation package to the root directory of the web server. You can also set up a virtual directory or virtual host.
  
You can use an existing database instead of creating a new one. Just ensure that the tables used by the WebIssues Server have a unique prefix to avoid clashes with other tables. This way you can also install multiple instances of the server sharing a single database. It is also possible to create multiple instances of the server within a single installation (see [[../Configuration#Multiple_Sites|Multiple Sites]] for more information).
+
=== Apache ===
  
The database user used by the WebIssues Server to login to the database must have sufficient privileges to create tables. The simplest solution for MySQL is to grant ALL PRIVILEGES to the database; for SQL Server assign the user to the database owner role. Refer to the database documentation for more information about privileges.
+
The source package contains the following .htaccess file which can be used with Apache and compatible web servers to configure permissions, default handler and error handlers:
  
In version 1.0 you don't have to edit the configuration file manually because the setup script will create it for you. If you want to change the connection options later, either modify the configuration file or delete it and run the setup script again. For security reasons it is not possible to run the setup script if the configuration file exists.
+
# protect include files and templates
 +
<FilesMatch (\.(inc\.php|html\.php|svn-base)$)>
 +
  Order allow,deny
 +
  Deny from all
 +
</FilesMatch>
 +
 +
# do not show directory listings
 +
Options -Indexes
 +
 +
# set the default handler
 +
DirectoryIndex index.php
 +
 +
# set error handlers
 +
ErrorDocument 401 /common/errors/handle401.php
 +
ErrorDocument 403 /common/errors/handle403.php
 +
ErrorDocument 404 /common/errors/handle404.php
  
== Security ==
+
Make sure that Apache is configured to handle the .htaccess file. Set the AllowOverride option to All in the configuration file for the Apache server or the appropriate virtual host or directory to enable these settings. You may also put some additional configuration options to this file depending on your server configuration; refer to the web server's manual for more information.
  
It is very important to make sure that the data/ and common/data/ directories are not accessible to unauthorized users. Especially the configuration file, which contains credentials for the database server, should be protected from unauthorized access. You can use the General Information page in the Administration Panel to check if the configuration file is protected (JavaScript support is required for this function to work).
+
If the server is installed in a subdirectory or a virtual directory, you should add appropriate prefixes to ErrorDocument URLs.
  
The source package contains .htaccess files which can be used with Apache and compatible web servers to protect access to those directories. Make sure that Apache is configured to handle the .htaccess file. Set the AllowOverride option to All in the configuration file for the Apache server or the appropriate virtual host or directory to enable these settings.
+
The data/ and common/data/ directories should be protected from accessing from the web. These directories also contain .htaccess files with the following content:
  
If you are using Windows and IIS server, go to Authorization Rule section for these two directories and create a rule to deny access from all users and remove all other rules. You can also create a Web.config file if you are using IIS 7 or newer (see [[#IIS_Configuration|below]]).
+
# deny access to all files in this directory
 +
Order allow,deny
 +
Deny from all
  
 
For more security it is recommended that the data files are stored outside of the WebIssues Server directory. See [[../Configuration#Directories|WebIssues configuration]] for more information.
 
For more security it is recommended that the data files are stored outside of the WebIssues Server directory. See [[../Configuration#Directories|WebIssues configuration]] for more information.
  
== Error Pages ==
+
It is also recommended to enable compression and static contents caching in order to improve the performance of the server. Refer to the documentation of Apache for more details.
 +
 
 +
The mod_security module may cause problems with WebIssues, for example block the Desktop Client or reject legitimate requests containing certain words. If you have mod_security installed, make sure that it is correctly configured and disable the rules that cause problems. Refer to mod_security documentation for more details. Alternatively, you can simply disable mod_security completely by adding the following lines to the main .htaccess file:
 +
 
 +
<IfModule mod_security.c>
 +
SecFilterEngine Off
 +
SecFilterScanPOST Off
 +
</IfModule>
 +
 +
<IfModule mod_security2.c>
 +
SecRuleEngine Off
 +
</IfModule>
  
The WebIssues server contains two scripts which can be used to handle 403 Forbidden and 404 Not Found errors. If you are using IIS, you can also handle the 500 Server Error. The error handler scripts are:
+
=== IIS ===
* common/errors/handle403.php
 
* common/errors/handle404.php
 
* common/errors/handle500.php
 
  
Those scripts not only provide user friendly error information which is consistent with the look of the WebIssues application, but they also add appropriate messages to the WebIssues event log.
+
Make sure that PHP and webcache extension is correctly configured. It is recommended to use the Microsoft Web Platform Installer to install PHP support for IIS. Visit http://php.iis.net/ for more information.
  
The .htaccess file distributed with the source package configures the error handlers for Apache. You may need to modify the path if the WebIssues Server is not installed in the root location of the web server.
+
In order to protect the data/ and common/date/ directories from accessing from the web, go to Authorization Rule section for these two directories and create a rule to deny access from all users and remove all other rules. You can also configure Request Filtering to disable access to files with .inc.php and .html.php extensions.
  
If you are using IIS, go to Error Pages section and add or modify the error pages for appropriate status codes. You can also use the Web.config file (see [[#IIS_Configuration|below]]).
+
For more security it is recommended that the data files are stored outside of the WebIssues Server directory. See [[../Configuration#Directories|WebIssues configuration]] for more information.
  
Files with .inc.php and .html.php extensions are protected from being executed directly through the URL, but they output a blank screen and no error is logged. The .htaccess file configures Apache to generate a 403 Forbidden error when these files are accessed. You can configure Request Filtering in IIS to achieve a similar behavior.
+
It is also recommended to set up custom Error Pages to handle HTTP 401, 403 and 404 errors, in order to provide user friendly error information which is consistent with the look of the WebIssues application, and to log appropriate messages in the WebIssues Event Log. The error handler scripts provided by the WebIssues Server are:
 +
* common/errors/handle403.php
 +
* common/errors/handle404.php
 +
* common/errors/handle500.php
  
Note that for security reasons WebIssues by default does not show detailed error information on the error pages. Error details are stored in the WebIssues event log and can be viewed through the Administration Panel. To make debugging easier, you may enable showing error details in the [[../Configuration#Debugging|WebIssues configuration]].
+
Note that for security reasons WebIssues by default does not show detailed error information on the error pages. Error details are stored in the WebIssues Event Log and can be viewed through the Administration Panel. To make debugging easier, you may enable showing error details in the [[../Configuration#Debugging|WebIssues configuration]].
  
== IIS Configuration ==
+
You can also use the following Web.config file to configure your IIS server:
  
To install WebIssues Server on Windows with IIS you first need to install PHP. The easiest way to do that is to use the Web Platform Installer. You should also install the Windows Cache Extension for significant improvement of performance. Visit http://php.iis.net/ for more information.
+
<?xml version="1.0" encoding="UTF-8"?>
 +
<configuration>
 +
  <system.webServer>
 +
    &lt;!-- protect include files and templates -->
 +
    <security>
 +
      <requestFiltering>
 +
        <hiddenSegments>
 +
          <clear />
 +
          <add segment=".htaccess" />
 +
          <add segment=".svn" />
 +
          <add segment="web.config" />
 +
        </hiddenSegments>
 +
        <denyUrlSequences>
 +
          <clear />
 +
          <add sequence=".html.php" />
 +
          <add sequence=".inc.php" />
 +
        </denyUrlSequences>
 +
      </requestFiltering>
 +
    </security>
 +
 +
    &lt;!-- do not show directory listings -->
 +
    <directoryBrowse enabled="false" />
 +
 +
    &lt;!-- set the default handler -->
 +
    <defaultDocument enabled="true">
 +
      <files>
 +
        <clear />
 +
        <add value="index.php" />
 +
      </files>
 +
    </defaultDocument>
 +
 +
    &lt;!-- set error handlers -->
 +
    <httpErrors errorMode="Custom">
 +
      <remove statusCode="401" subStatusCode="-1" />
 +
      <remove statusCode="403" subStatusCode="-1" />
 +
      <remove statusCode="404" subStatusCode="-1" />
 +
      <error statusCode="401" prefixLanguageFilePath="" path="/common/errors/handle401.php" responseMode="ExecuteURL" />
 +
      <error statusCode="403" prefixLanguageFilePath="" path="/common/errors/handle403.php" responseMode="ExecuteURL" />
 +
      <error statusCode="404" prefixLanguageFilePath="" path="/common/errors/handle404.php" responseMode="ExecuteURL" />
 +
    </httpErrors>
 +
  </system.webServer>
 +
 +
  &lt;!-- protect data directory -->
 +
  <location path="data">
 +
    <system.webServer>
 +
      <security>
 +
        <authorization>
 +
          <remove users="*" roles="" verbs="" />
 +
          <add accessType="Deny" users="*" />
 +
        </authorization>
 +
      </security>
 +
    </system.webServer>
 +
  </location>
 +
 +
  &lt;!-- protect common data directory -->
 +
  <location path="common/data">
 +
    <system.webServer>
 +
      <security>
 +
        <authorization>
 +
          <remove users="*" roles="" verbs="" />
 +
          <add accessType="Deny" users="*" />
 +
        </authorization>
 +
      </security>
 +
    </system.webServer>
 +
  </location>
 +
</configuration>
  
If you are using Windows with IIS verson 7 or newer, you can quickly configure the security settings and error pages by copying the attached [http://wiki.mimec.org/files/3/34/Web.config Web.config] file to the root directory of the WebIssues Server. Note that you may need to modify the paths of the error pages if the WebIssues Server is not installed in the root location of the web server.
+
Note that if the server is installed in a subdirectory or a virtual directory, you should add appropriate prefixes to the error page URLs.
  
Alternatively you can host WebIssues Server on Windows using XAMPP, which includes Apache, MySQL and PHP. Visit http://www.apachefriends.org/en/xampp.html for more information.
+
It is also recommended to enable compression and static contents caching in order to improve the performance of the server. Refer to the documentation of IIS for more details.
  
 
== Cron Job ==
 
== Cron Job ==
 
In order to be able to receive notification emails from WebIssues Server, you need to configure the cron job (scheduled task) to run periodically. The job should be executed at least once per hour, but in order to receive immediate notifications quicker an interval between 5 and 15 minutes is recommended.
 
  
 
On Linux usually the crontab file can be used to configure jobs executed periodically. For example, adding the following line to this file will run the cron.php script every hour:
 
On Linux usually the crontab file can be used to configure jobs executed periodically. For example, adding the following line to this file will run the cron.php script every hour:
Line 78: Line 214:
  
 
On Windows you can create a task in the Task Scheduler that executes the script. Enter php.exe (with appropriate path) as the program, <tt>cron/job.php</tt> as the argument and the location where the WebIssues Server is installed as the start directory. Use the advanced settings on the Triggers tab to configure the task to repeat with desired interval.
 
On Windows you can create a task in the Task Scheduler that executes the script. Enter php.exe (with appropriate path) as the program, <tt>cron/job.php</tt> as the argument and the location where the WebIssues Server is installed as the start directory. Use the advanced settings on the Triggers tab to configure the task to repeat with desired interval.
 
Open the General Information page in the Administration Panel to make sure that the cron job is running. Also every execution of the job is logged in the Event Log of the WebIssues Server.
 

Revision as of 18:37, 12 November 2013

This page contains platform specific installation notes for WebIssues Server 1.1. For general information about installing the server, refer to the WebIssues manual.

Database

You can use an existing database instead of creating a new one. Just ensure that the tables used by the WebIssues Server have a unique prefix to avoid clashes with other tables. This way you can also install multiple instances of the server sharing a single database. It is also possible to create multiple instances of the server within a single installation (see Multiple Sites for more information).

The database user used by the WebIssues Server to login to the database must have sufficient privileges to create tables. The simplest solution for MySQL is to grant ALL PRIVILEGES to the database; for SQL Server assign the user to the database owner role. Refer to the database documentation for more information about privileges.

In version 1.1 you don't have to edit the configuration file manually because the setup script will create it for you. If you want to change the connection options later, either modify the configuration file or delete it and run the setup script again. For security reasons it is not possible to run the setup script if the configuration file exists.

The following information can be used to set up the database using command line tools.

MySQL

1. Create the database (dbauser is the login of the database administrator, database is the name of the database to create):

mysqladmin -u dbauser -p create database

You will be prompted for the database administrator's password.

2. Connect to the database server:

mysql -u dbauser -p

From the MySQL command prompt execute the following query to create a user with access to the database (user is the user's login, password is the user's password and database is the name of the database):

GRANT ALL PRIVILEGES ON database.* TO 'user'@'localhost' IDENTIFIED BY 'password';

3. Execute the following query to activate the new permissions:

FLUSH PRIVILEGES;

PostgreSQL

1. Create the user account (user is the user's login):

createuser --pwprompt --encrypted --no-adduser --no-createdb user

You will be prompted for the password for the new user. Note that you have to log in as a user with appropriate permissions to manage the PostgreSQL server.

2. Create the database (user is the user's login, database is the name of the database to create):

createdb --encoding=UNICODE --owner=user database

SQL Server

1. Connect to the database server:

sqlcmd.exe -U dbauser -P dbapassword

Replace dbauser and dbapassword with the login and password of the database administrator.

2. Execute the following queries to create a user's login and the database (user is the user's login, password is the user's password and database is the name of the database to create):

CREATE LOGIN user WITH PASSWORD = 'password';
GO
CREATE DATABASE database;
GO

3. Execute the following queries to assign appropriate permissions for the database to the user (user is the user's login, database is the name of the database):

USE database;
GO
EXEC sp_grantdbaccess 'user';
GO
EXEC sp_addrolemember 'db_owner', 'user';
GO

Web Server

Copy the contents of the server installation package to the root directory of the web server. You can also set up a virtual directory or virtual host.

Apache

The source package contains the following .htaccess file which can be used with Apache and compatible web servers to configure permissions, default handler and error handlers:

# protect include files and templates
<FilesMatch (\.(inc\.php|html\.php|svn-base)$)>
  Order allow,deny
  Deny from all
</FilesMatch>

# do not show directory listings
Options -Indexes

# set the default handler
DirectoryIndex index.php

# set error handlers
ErrorDocument 401 /common/errors/handle401.php
ErrorDocument 403 /common/errors/handle403.php
ErrorDocument 404 /common/errors/handle404.php

Make sure that Apache is configured to handle the .htaccess file. Set the AllowOverride option to All in the configuration file for the Apache server or the appropriate virtual host or directory to enable these settings. You may also put some additional configuration options to this file depending on your server configuration; refer to the web server's manual for more information.

If the server is installed in a subdirectory or a virtual directory, you should add appropriate prefixes to ErrorDocument URLs.

The data/ and common/data/ directories should be protected from accessing from the web. These directories also contain .htaccess files with the following content:

# deny access to all files in this directory
Order allow,deny
Deny from all

For more security it is recommended that the data files are stored outside of the WebIssues Server directory. See WebIssues configuration for more information.

It is also recommended to enable compression and static contents caching in order to improve the performance of the server. Refer to the documentation of Apache for more details.

The mod_security module may cause problems with WebIssues, for example block the Desktop Client or reject legitimate requests containing certain words. If you have mod_security installed, make sure that it is correctly configured and disable the rules that cause problems. Refer to mod_security documentation for more details. Alternatively, you can simply disable mod_security completely by adding the following lines to the main .htaccess file:

<IfModule mod_security.c>
SecFilterEngine Off
SecFilterScanPOST Off
</IfModule>

<IfModule mod_security2.c>
SecRuleEngine Off
</IfModule>

IIS

Make sure that PHP and webcache extension is correctly configured. It is recommended to use the Microsoft Web Platform Installer to install PHP support for IIS. Visit http://php.iis.net/ for more information.

In order to protect the data/ and common/date/ directories from accessing from the web, go to Authorization Rule section for these two directories and create a rule to deny access from all users and remove all other rules. You can also configure Request Filtering to disable access to files with .inc.php and .html.php extensions.

For more security it is recommended that the data files are stored outside of the WebIssues Server directory. See WebIssues configuration for more information.

It is also recommended to set up custom Error Pages to handle HTTP 401, 403 and 404 errors, in order to provide user friendly error information which is consistent with the look of the WebIssues application, and to log appropriate messages in the WebIssues Event Log. The error handler scripts provided by the WebIssues Server are:

  • common/errors/handle403.php
  • common/errors/handle404.php
  • common/errors/handle500.php

Note that for security reasons WebIssues by default does not show detailed error information on the error pages. Error details are stored in the WebIssues Event Log and can be viewed through the Administration Panel. To make debugging easier, you may enable showing error details in the WebIssues configuration.

You can also use the following Web.config file to configure your IIS server:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
 <system.webServer>
    <!-- protect include files and templates -->
    <security>
      <requestFiltering>
        <hiddenSegments>
          <clear />
          <add segment=".htaccess" />
          <add segment=".svn" />
          <add segment="web.config" />
        </hiddenSegments>
        <denyUrlSequences>
          <clear />
          <add sequence=".html.php" />
          <add sequence=".inc.php" />
        </denyUrlSequences>
      </requestFiltering>
    </security>

    <!-- do not show directory listings -->
    <directoryBrowse enabled="false" />

    <!-- set the default handler -->
    <defaultDocument enabled="true">
      <files>
        <clear />
        <add value="index.php" />
      </files>
    </defaultDocument>

    <!-- set error handlers -->
    <httpErrors errorMode="Custom">
      <remove statusCode="401" subStatusCode="-1" />
      <remove statusCode="403" subStatusCode="-1" />
      <remove statusCode="404" subStatusCode="-1" />
      <error statusCode="401" prefixLanguageFilePath="" path="/common/errors/handle401.php" responseMode="ExecuteURL" />
      <error statusCode="403" prefixLanguageFilePath="" path="/common/errors/handle403.php" responseMode="ExecuteURL" />
      <error statusCode="404" prefixLanguageFilePath="" path="/common/errors/handle404.php" responseMode="ExecuteURL" />
    </httpErrors>
  </system.webServer>

  <!-- protect data directory -->
  <location path="data">
    <system.webServer>
      <security>
        <authorization>
          <remove users="*" roles="" verbs="" />
          <add accessType="Deny" users="*" />
        </authorization>
      </security>
    </system.webServer>
  </location>

  <!-- protect common data directory -->
  <location path="common/data">
    <system.webServer>
      <security>
        <authorization>
          <remove users="*" roles="" verbs="" />
          <add accessType="Deny" users="*" />
        </authorization>
      </security>
    </system.webServer>
  </location>
</configuration>

Note that if the server is installed in a subdirectory or a virtual directory, you should add appropriate prefixes to the error page URLs.

It is also recommended to enable compression and static contents caching in order to improve the performance of the server. Refer to the documentation of IIS for more details.

Cron Job

On Linux usually the crontab file can be used to configure jobs executed periodically. For example, adding the following line to this file will run the cron.php script every hour:

0 * * * * php /var/www/html/cron/job.php

You may need to adjust the path to the php executable and to the script file. See the documentation of cron for more details.

On Windows you can create a task in the Task Scheduler that executes the script. Enter php.exe (with appropriate path) as the program, cron/job.php as the argument and the location where the WebIssues Server is installed as the start directory. Use the advanced settings on the Triggers tab to configure the task to repeat with desired interval.