====== Installation on a Web Server ======

This chapter describes the installation of SoSci Survey on an own web server.

If you want to update an already existing installation of SoSci Survey, please read [[update|Update of the installation]].


**Note:** This chapter is __not__ relevant if you want to use SoSci Survey on an already existing survey server (e. g. [[https://www.soscisurvey.de|www.soscisurvey.de]]). There you can directly register a user account and a survey project without installation ([[:en:start|Overview]]).

**Note:** SoSci Survey is __not__ publicly available for download. Companies can purchase server licenses to run their own survey server ([[https://www.soscisurvey.de/index.php?page=pricing|prices and fees]]). Academic institutions receive a free [[https://www.soscisurvey.de/index.php?page=edu-licence|university license]] upon request.

===== System Requirements =====

To install SoSci Survey you need a working web server with PHP and database support. The installation of SoSci Survey requires the following software:

  * Web server (usually Apache or IIS) or Webspace (see below)
  * PHP version 5.5.0 or higher
  * MySQL database version 5.5.3 or higher

Recommended for optimal operation:

  * possibility to execute scripts in a time-controlled manner (Cron jobs)
  * PHP operation without restrictions (not in safe mode)

The task of the web server is to provide contents from the server to the internet/intranet. For this to work, the web server and firewall must be configured correctly. Please make sure that the web server is accessible via HTTP/HTTPS protocol.

**Tip:** If you don't have a web server yet and want to set up a local server under Windows, the [[http://www.apachefriends.org/de/xampp.html|xampp]] installation package of the Apache Friends saves a lot of work. It includes among other things a pre-configured Apache web server and MySQL.

**Note:** Most of the cheap webspace offers of the hosters are so-called shared hosting. There are hundreds or thousands of Internet offers running on a web server. This webspace is already offered at prices of less than 2 EUR per month. In order that the offers on such a server do not get in the way of each other, the functions are often limited a little bit (e. g. PHP runs in the so-called Safe Mode). In return, there is no need to worry about installing and setting up the web server for shared hosting.

===== Prearrangement =====

The following software is helpful or required for installation:

  * If the server is not running on the local computer, you will need an FTP program to transfer files to the server, such as [[http://filezilla-project.org/|FileZilla]].
  * A frontend such as [[http://www.heidisql.com/|HeidiSQL]] is helpful for maintaining the database.
  * If you haven't done so yet, download the latest SoSci Survey installation package from the [[https://www.soscisurvey.de/download/|download portal]]. For the download you need your license data (password).

If you are not familiar with rights management on web servers, please read [[users|Processes and Users on a Web Server]].

===== Prepare Server =====

In order for the server to work correctly with SoSci Survey, you may need to create a directory for SoSci Survey and make further adjustments.

  * [[prepare1|Preparation of the server I]]
  * [[prepare2apache|Preparation of the server II (Apache)]]
  * [[prepare2iis|Preparation of the server II (Microsoft IIS)]]

===== Configure Database =====

In order for SoSci Survey to access the database, you need a username and password for the database.

**Important:** A database user specifically for SoSci Survey increases the security of the server against attacks. Therefore, it is strongly recommended to set up your own database and user for SoSci Survey.

In the case that you use the database administrator's user account (e. g."root") to access the database, SoSci Survey will be able to create a database on its own -- you can skip this section. 

  * Create a database for SoSci Survey on the database server. SoSci Survey can also be installed in an existing database (e. g. if only one database is available). **Important:** The database name may only contain lowercase letters (and characters allowed in MySQL)! 
  * If necessary, create a new SoSci Survey user on the database server who has all rights for the SoSci Survey database (create, delete, change, etc.) but no rights for other databases. This user should __only__ be allowed to log into the database from the web server (normally the "localhost").

===== Copy SoSci Survey to the Web Server =====

Unpack the SoSci Survey installation package and copy the files into the directory you provided on the server.

The following examples assume that you install SoSci Survey on the server //%%www.domain.tld%%// in the subdirectory or alias ///sosci//. The URL of the server accordingly was //%%http://www.domain.tld/sosci/%%//. Please replace the domain with the correct domain and the directory of your installation directory. For example, if you access the local computer, the correct URL is //%%http://127.0.0.1/sosci/%%// (usually an IP address is used instead of the domain name on the local computer).


First of all, test whether you can reach SoSci Survey via the Intranet or Internet. To do this, call up the URL //%%http://www.domain.tld/sosci/admin/-reach.php%%// in your Internet browser. The hyphen (-) is important. If the web server is accessible correctly, the browser window now shows "reach".

In the following some common problems are described. If necessary, please also read the instructions for [[prepare2apache|Preparing Server II (Apache)]] or [[prepare2iis|Preparing Server II (Microsoft IIS)]].

  * If the browser loads for a long time and then displays an empty page or a timeout, the web server has either not yet been started, the domain name is not correct (note that new domains are only accessible after a few hours) or the server is not reachable (e. g. because the firewall blocks the connection).
  * If you get an error message "404 not found" (or similar), the specified directory is incorrect or the installation directory is not in the path for web documents or no alias has been defined. To be on the safe side, make sure that the domain/IP address is spelled correctly.
  * If you get an error message saying "permission denied", (or similar), the directory is not released for access from the Internet. Here the documentation of the web server helps.
  * If you see HTML code, your web server delivers the file as a text file and not as HTML. In this case, the MIME settings of the web server for PHP files must be corrected.

Now test whether PHP scripts are processed correctly. To do this, call up the URL //%%http://www.domain.tld/sosci/admin/-php.php%%// in your Internet browser. Now "php" should appear in your browser.

  * If "failed" or an other code appears, PHP files are not yet forwarded to the PHP interpreter, but are delivered directly from the web server. In this case, the web server must be configured correctly.

===== Access Rights =====

In most cases, the web server is only allowed to read files on the hard disk. Therefore, you have to assign write permissions for some directories manually. The configuration of write permissions varies depending on the server:

  * If you access the server via FTP: [[permissions_ftp|Write Permission (FTP)]] 
  * If you are using a Linux server: [[permissions_linux|Write Permissions (Linux)]] 
  * If you are using a Windows server: [[permissions_win|Write Permissions (Windows)]]

Please grant the web server (i. e. the operating system user whose rights the web server acts with) write permission for the following directories:

  * The installation directory to which you copied SoSci Survey. This is necessary because a separate subdirectory is created for each new survey project. Set write permissions only for the installation directory and __not__ for the files and directories contained therein.
  * All files and directories in the subdirectory //system//, if this already exist. The configuration is stored here and log files as well as temporary files are filed. **Note:** The directory //system// is only created by the installation routine -- if the web server has correct write permissions for the higher-level directory, the permissions are set automatically.

The web server needs to access some directories, but web server users (internet surfers) are not allowed to access them. This must be ensured by configuring the web server accordingly.

The installation package contains some files called. htaccess -- these files govern, among other things, the access rights on a default Apache web server. Test the correct function by checking the URLs //%%http://www.domain.tld/sosci/inc/-reach.php%%// and //%%http://www.domain.tld/sosci/system/-reach.php%%// 

  * If you get a message "permission denied" (or similar), everything is configured correctly.
  * If you can access the files and you are using an Apache server, the configuration via. htaccess has probably been disabled. In this case, you must disable access in the Apache configuration (e. g. ///etc/apache2/httpd.conf// or //apache/conf/httpd.conf//) with a directory directive. You must specify the installation directory plus ///inc// or ///system//, e. g.
 

<code>
<Directory /var/www/sosci/inc/>
  Order allow,deny
  deny from all
</Directory>
<Directory /var/www/sosci/system/>
  Order allow,deny
  deny from all
</Directory>
</code>

  * If you use the IIS 7:\\ (The exact procedure step by step is described on [[http://www.iis.net/ConfigReference/system.webServer/security/requestFiltering|IIS: Request Filtering]])
    * Select //IIS Request Filtering//
    * Select the tab  //URL//
    * Click on  //Deny Sequence//
    * Enter "/inc" in the pop-up and repeat the procedure for "/system".
  * If you are using an older IIS::
    * Open the configuration tool  (//configuration tool//) via Start -> Settings -> Control Panel -> Administrative Tools -> Internet Information Services
    * Navigate to the installation directory and there to  ///inc//: Local Computer -> Web Sites -> Default Web Site -> Installation Directory -> inc
    * Right-click to display the settings for the directory: Properties -> Directory Security -> IP address and domain name restrictions -> Edit
    * Select "By default, all computers will be: Denied access"
    * Repeat the last two steps for ///system//

===== PHP Settings =====

The installation routine (see below) checks the PHP settings and warns about possible problems. A setting that usually needs to be changed affects file sizes:

  * By default, PHP only accepts files up to 2 MB when you upload files in a form. If SoSci Survey should also support the upload of media files, this is not enough.
    * For this reason, set the value ''upload_max_filesize'' in the file //php.ini// to ''32M''.
    * If the variable ''post_max_size'' has a smaller value, enter ''32M'' ein. The latter also avoids problems with very extensive questionnaires (e. g. a lot of HTML or PHP code).
    * If the ''memory_limit'' setting is set to a value less than ''32M'', it must also be increased so that the upload of large files works correctly. In order to reach the upper limit of 32 MB during the upload, this value must be even slightly higher (e. g. 33M), because oFb itself also needs some memory.
  * If many files (e. g. images) have to be uploaded in a survey, it makes sense to transfer all images in one step. The ''max_file_uploads'' setting regulates how many files are transferred at the same time. The default configuration with 20 images may be a bit tight and can be increased to 50 or 100, for example.

The other PHP settings are already suitable for SoSci Survey with a standard installation. The necessary changes are described below if the installation routine sounds an alarm.

  * The safe mode of PHP should be deactivated so that scripts are not aborted after 30 seconds.
    * The maximum runtime for PHP script is limited by the PHP setting "max_execution_time". However, when downloading large datasets or performing server maintenance, it is necessary that the script can remove this restriction. This is only possible for the script if PHP is not running in  "Safe Mode".
    * To disable Safe Mode, look for the **safe_mode** entry in PHP.INI and enter the value **off**.
    * It does  __not__ make sense to change the setting for **max_execution_time** in PHP.INI. The default value of 30 seconds ensures that incorrectly programmed questionnaires (e. g. with an endless loop) are aborted.
  * SoSci Survey requires a number of PHP modules to run correctly.
    * Required are: `mysql`, `mbstring`, `zip`, `gd`, `curl` and under PHP 5 possibly `pcre` und `zlib`.
    * Under Linux, these libraries are installed using appropriate packages, e. g. `sudo apt-get install php-mysql php-mbstring php-zip php-gd php-curl`.
    * Under Windows (e. g. XAMPP) a library can be easily activated by removing the semicolon in front of the corresponding ''extension'' line in //PHP.INI//. The web server must then be restarted.
    * After activating/supplementing modules, it may be necessary to restart the web server, under Debian-Linux for example with ''/etc/init.d/apache2 restart''.

===== MySQL Settings =====

A standard MySQL installation is usually well suited for running SoSci Survey. Nevertheless, take a look at the following settings. You can query a setting with the SQL command ''%%SHOW VARIABLES LIKE "max_user_connections"%%'', whereby the last part is of course replaced by the relevant variable.

  * MySQL should allow sufficient connections to the database. If the maximum number of allowed connections per user ''max_user_connections'' is too low (e. g. 16 or less), this may limit the number of concurrent respondents.
  * With shared hosting offers, you should check the ratio of the settings for  ''max_user_connections'' and ''max_connections'': If the hoster means well and sets both values to the same high value (e. g. 512), this can cause the problem of database overload -- by another user on the server who uses all connections (e. g. a faulty script).

===== Initialization =====

  * Access the SoSci Survey directory in your browser via -- HTTP bzw. HTTPS: (//%%http://www.domain.tld/sosci/%%//). The URL consists of domain and directory.
  * You should now see a hint that an installation is required -- follow the link.
    * **Note:** The installation (//admin/install.php//) can alternatively be accessed directly (//%%http://www.domain.tld/sosci/admin/install.php%%//).
    * **Note:** When calling up or during the installation, there may be longer waiting times (up to approx. 2 minutes). The installation then tests the database and server configuration.
  * The installation routine now asks you to provide the access data for the database server (database user) and some additional information. Please also take seriously the directions of the installation routine for possible problems.
    * **Note:** You can change or adjust all settings later.
    * **Note:** If you do not want unknowns to set up a survey project on your server, you should enter a //login password// in the settings. 
    * **Note:** If nothing happens for a long time after the database server has been specified and/or a blank page appears, the address of the database server is probably incorrect.  Windows Server sometimes does __not__ accept the entry "localhost" and expects the IP address //127.0.0.1//instead. Test the access data with a tool like [[http://www.heidisql.com|HeidiSQL]].

===== Completion of the Installation =====

After successful installation, you can log in as an administrator. You should set a password immediately:

  * Log in to the administrator login "admin".
  * After logging in, please first enter an email address for the administrator account, under  **Useraccount** -> **User Data**.
  * Under **Server Administration** -> "Server Settings" you can now make further settings for the server.

Now the installation is complete. From now on, additional user accounts can be registered and survey projects can be set up  ([[en:create:register|set up Useraccount and Survey]]).

===== Automation of Regular Tasks =====

For an optimal execution of SoSci Survey, two PHP scripts should be called regularly: [[maintenance|Regular Maintenance of the Server]] (once a day) and [[:en:server:crontask|Execution of Time-Controlled Tasks]].


===== Further Steps =====

  * SoSci Survey knows a number of extensions that you can now install: [[plugins|Extensions]].
  * The chapter [[data|Data in SoSci Survey]] gives you an overview of where SoSci Survey stores which data.
  * There are a number of ways to [[performance|Optimize Server Performance ]].
  * To adjust non-modifiable settings [[config|the configuration can be changed manually ]].
  * The procedure for updating an existing installation is described in the chapter  [[update|Update of the Installation]].