# WebIssues Manual

## Version 1.0.4

Home » Preparing the system
« Preparing the system
Initial setup »

## Installation

After ensuring that the required components are installed and configured, and creating the database, you can proceed to the installation of the WebIssues server itself.

### Copying files

Download and unpack the WebIssues server package — it contains a directory named `webissues-x.y` (where `x.y` is the version of the package). Then move all files and subdirectories from that directory to the root directory of the web server. External hosting services usually use the FTP protocol for copying files to the server, so you'll need an FTP client.

### Note

It's possible to install WebIssues server along with the other web sites and applications operating on the same computer. You can install the server in a subdirectory located in the root directory of the web server, as well as on a virtual host or in a virtual directory. Refer to the documentation of your web server or hosting service for more information.

You can also create multiple separate instances of the WebIssues server in a single installation. Individual instances can be accessed through different domain names or subdomains, or in different virtual subdirectories. For more information, please visit http://wiki.mimec.org/wiki/WebIssues/Configuration.

Then give all users, or the user which the web server runs as, write permission to the `data/sites` subdirectory. To do this, use the file manager or the FTP client, or run the `chmod` command from the command line. A configuration file will be created in this directory during the installation. Also files attached to the issues will be stored there.

### Warning

Make sure the `data` and `common/data` directories are protected from unauthorized access using the web browser. Otherwise unauthorized persons will be able, for example, to download attachments stored in the system. If you're using Apache, you can use the `.htaccess` files which are included in the source package for that purpose. For more information, please visit http://wiki.mimec.org/wiki/WebIssues/Installation.

After the installation, also make sure that the WebIssues system configuration file is protected against unauthorized access, since it contains the username and password used to connect to the database. This is particularly important when using public hosting services.

To ensure maximum security, it's recommended that configuration files and attachments are not stored in the `data` directory, but in a different location, outside the root directory of the web server. More information about changing the location of the directory containing these files can be found at http://wiki.mimec.org/wiki/WebIssues/Configuration.

### System setup

Now you can open the homepage of the WebIssues system. Launch your favorite web browser and enter the URL of the server, for example `http://www.example.com`. You should see the following message:

Figure 2.1. Welcome message

If you follow the instructions and click on the link, you will be prompted to select the language that will be used during the installation. It will also be the default language in which the WebIssues system will display all messages.

In the next step of the installation, basic information about your server will be displayed: the name of the instance (usually `default`, unless you create multiple instances of the server within a single installation), the base URL of the server and the path of the directory in which the configuration file will be created. You will also see the version of PHP, the web server and the operating system, and the name of the computer on which you're installing WebIssues. After verifying this information, proceed to the next step.

Figure 2.2. Configuring the database connection

You will be asked to enter information necessary to connect to the database that you previously created. You must first determine its type; depending on your PHP configuration, you can choose a MySQL, PostgreSQL or SQL Server database. If any of these options is not available, it means that the required PHP extension is not installed or is disabled.

Then enter the host name of the database server, if it's located on a different computer than the web server, the name of the database and the login and password of a user with the right to create tables in the database. In case of SQL Server, you can leave the user name and password blank to use integrated Windows authentication.

### Note

During installation, you can also specify a prefix which will be added before the names of all tables and other objects in the database. For example, if you choose `wi_`prefix, tables named `wi_server`, `wi_users`, etc., will be created.

By choosing a unique prefix, you can install many different applications using a single database. You can also create several separate instances of the WebIssues server in a single database.

Enter the necessary information and proceed to the next step. The WebIssues system will try to connect to the database server, and in case of an error it will display an appropriate message. If the connection succeeds and the database doesn't already contain the tables required by the system, you will see the following page:

Figure 2.3. Parameters of the new server

Enter the name of the server which will be visible to all users in the upper left corner of the page. Also enter the password for the Administrator account, which you can later use to log into the server and change its settings.

By default, the installer will create several predefined types of issues and views. You should leave this setting to quickly start working with the system. Later you will be able to freely adjust and even remove those built-in types. However, if you want to manually create all types of issues from scratch, select Do not install any issue types.

### Note

You can import data from version 0.8.5 of the WebIssues server to the new version of the system. The new server must be installed in the same database as its previous version. Therefore you must use a different prefix for the names of the new tables, than the one that was used in version 0.8.5. Select Import data from WebIssues Server 0.8.5 and optionally enter a prefix for the source tables.

When installing a new server, all data stored in the database is copied, but the source tables are not modified or removed. Thus, if the import process fails, you can correct any errors and try installing the new version again. If attachments were stored in the file system, you must also copy them from the old version to the appropriate directory in the new version of the server; the installer will not do it automatically.

If version 0.8.5 of the system used a version of the database earlier than the currently required version, before the installation you must first update the database server to a newer version. After updating a MySQL database from a version older than 4.1, you also need to convert all text columns to binary, and then back to text with `utf8` encoding, in order to ensure proper encoding of text. Read http://dev.mysql.com/doc/refman/4.1/en/charset-conversion.html for more information about converting columns.

Go to the next page, which contains a brief summary of the operations that will be performed. Click Install to begin the installation. This may take a few seconds, or a bit longer in case of importing existing data. If the installation is successful, a message will appear.

If you want to create a new configuration file for a previously created server, enter the connection parameters for the database containing data of the server instance. The page used for entering parameters of a new server will be omitted in this case, and the database will not be modified in any way. Instead, the installer will display the name and other information about the existing server, and the installation process will only create a new configuration file.

### Tip

In order to create a new configuration file in the future, for example after moving the database to another server, you must first delete an existing configuration file. This is a protection against unauthorized access to the installation procedure.

« Preparing the system
Initial setup »