Installation and setup  

What are the system requirements for installing The Bug Genie?  

To be installed, The Bug Genie requires the following:

• A web server, with URL rewriting capabilities
• PHP version 7.0.0 or later. PHP version 5.6.x or lower is not supported.
• A supported database (!MySQL >= 5.0 or !PostgreSQL >= 8.2 ) and php modules for this database
• The PHP gmp extension
• For project statistics, the PHP gd extension needs to be installed
• For incoming email support, the PHP imap extension needs to be installed

How do I upgrade to the latest release?  

PS: For known issues and caveats when upgrading, please see Upgrade notes.

4.1.0 -> Any 4.x release  

From version 4.1.1, updating The Bug Genie to any subsequent release is done by following these steps:

• Upload the updated archive to the root directory of your The Bug Genie installation, replacing and overwriting files as prompted
• Create an empty file in the root directory, called

  upgrade

  On Linux/Unix, this can be done by simply issuing this command

  touch ./upgrade

• Open the frontpage of The Bug Genie and the upgrade will start. Follow the on-screen prompts, and remember to remove the upgrade file when the upgrade is completed (if you don't remove the upgrade file, you may end up in a login/redirect loop).

4.0.1 to 4.1.x  

(thanks to user @dezlov for compiling these instructions)

1. Disable The Bug Genie by using the "Maintenance mode" setting
2. Make a backup of the existing `thebuggenie` folder and the database
3. Download the latest 4.1.x version archive from <https://github.com/thebuggenie/thebuggenie/releases>
4. Unpack the downloaded archive into a new folder
5. Install Composer (<https://getcomposer.org/download/>) and use composer to install TBG dependencies

    - `php composer.phar install`

1. Copy the files `installed` and `core/config/b2db.yml` from the old `thebuggenie` directory to the new, downloaded directory
2. Create an empty file called `upgrade` in the root folder of the new `thebuggenie` directory
3. Create an empty folder called `cache` in the root of the new `thebuggenie` directory, and make sure your web server has write access to it
4. Copy over uploaded files (e.g. `upload` folder) to the new `thebuggenie` directory, and rename the folder to `files`
5. Point the web root in your web server configuration to the `public` folder in the new `thebuggenie` directory
6. Open the `/upgrade` URL in the web browser to start upgrade process, and follow the on-screen instructions.
7. Remove the `upgrade` file in the root of the new `thebuggenie` directory as instructed by the upgrade process (or when it finishes).

3.2.7 -> 4.0  

The Bug Genie internals has changed a lot between these two releases. To avoid conflicts and errors, make sure the following pre-conditions are met before you follow the instructions in the attached UPGRADE.md:

• Remove the folder /core/cache entirely, including subfolders and/or files
• Create a folder named "cache" under the root thebuggenie/ folder
• Copy the file core/config/b2db.sample.yml -> core/config/b2db.yml, and use the values from core/b2db_bootstrap.inc.php to populate the file you copied. If you don't have this file in your download, use the attached file instead.
• Remember to update your web server setup to point to the public/ subfolder (was previously thebuggenie/)
• Remove the contents of the public/css folder, and make a symlink from themes/oxygen/css (target) to public/css/oxygen (link name)

3.2.x -> 3.2.7  

Download the archive from the main download site. Extract the files into your current installation, overwriting existing files where prompted. When this is done, clear the contents of the B2DB cache folder (don't delete the folder, just its contents):

 core/cache/B2DB

You will want to clear the apc (in-memory) cache as well. If you're running your own server, this can be done by restarting or reloading the web-server. If this is not an option, you can edit modules/main/about.html.php and add this line at the top:

<?php TBGContext::clearCacheKeys(); ?>

Then visit

 http://<tracker>/about

Remember to revert your changes.

3.1.x -> 3.2.x or 3.0.1 -> 3.1.x  

Download the main archive from the download site. Extract the files into your current installation, overwriting existing files where prompted. When this is done, clear any files the cache folders (don't delete the folder or any containing folders, just files in the folders):

 core/cache/B2DB
 core/cache

Also make sure you clear the web server cache by either restarting the web server or disabling apc.

The upgrade helper needs write access to the following two files:

 ./installed #This file will be altered with version information
 ./upgrade #This file will be deleted

IMPORTANT:
You cannot update directly from 3.0 to 3.2. Upgrades can only be performed from one point release to another, such as 3.0 -> 3.1, and then 3.1 -> 3.2.

Make sure your installed file contains the correct version number. In some releases of The Bug Genie, the installer would write an incorrect version number to this file during installation. If you're running a clean installation of 3.1.x, it should say

 3.1, installed <date>

If you're running 3.1.x, upgraded from 3.0.x, it should say

 3.0, installed <date>
 3.1, upgraded <date>

You can find your version at

 <http://trackername>/about

The upgrade file doesn't exist. Create it to enable upgrading, and then open up the your bug tracker with the following url, which will launch the upgrade helper:

 <http://trackername>/upgrade

When the upgrade helper is completed, your installation will be upgraded to the new version.

3.1 -> 3.1.x or 3.0 -> 3.0.x  

Download the archive from the main download site. Extract the files into your current installation, overwriting existing files where prompted. When this is done, clear the contents of the B2DB cache folder (don't delete the folder, just its contents):

 core/cache/B2DB

Upgrading from ANY pre-release / beta version -> ANY other version  

We do not support upgrading from pre-release, beta or RC versions. Please perform a clean install of the latest stable release, or perform an upgrade from an earlier stable release if available.

Upgrading from 3.2 RC4 or later -> 3.2 RC5 or 3.2 final  

Please see the upgrade notes for the different release candidates, here: ReleaseCandidateUpgrades

What are the required database permissions for installing and using The Bug Genie?  

The Bug Genie does not require any special database permission for normal usage, except the following:

 SELECT, UPDATE, INSERT, DELETE

During installation, however, tables are created, and as such the database user used during installation also requires the following permissions:

 CREATE, ALTER, INDEX

If you want to change the database user used in normal operations, after the installation has been completed, you can do so by updating the username located in the following file:

 core/b2db_bootstrap.inc.php

What files should I back up when upgrading or reinstalling The Bug Genie?  

A general overview of the folder structure of The Bug Genie is available in the development section in the wiki. Worth noting is that The Bug Genie stores configuration and installation information in the following files (from project root):

 /installed
 /core/b2db_bootstrap.inc.php

/installed
This file contains version information and timestamp from when the installation took place. The file is required for The Bug Genie to run, as it is being pinged everytime The Bug Genie is initialized. The file usually contains something like this:

 3.0, installed 29.04.2011 21:45

After upgrade, it will contain something like this:

 3.1, upgraded 30.04.2011 20:11
 3.0, installed 29.04.2011 21:45

/core/b2db_bootstrap.inc.php
This file contains the database connection details. Contents usually looks like this:

<?php
        /**
         * B2DB sql parameters
         *
         * @author Daniel Andre Eikeland <zegenie@zegeniestudios.net>
         * @version 2.0
         * @license http://www.opensource.org/licenses/mozilla1.1.php Mozilla Public License 1.1 (MPL 1.1)
         * @package B2DB
         * @subpackage core
         */

        self::setUname('db_user');
        self::setPasswd('password');
        self::setTablePrefix('tbg3_');

        self::setDSN('mysql:host=localhost;dbname=thebuggenie_db');

In addition, the apache .htaccess file is located inside the public directory:

 thebuggenie/.htaccess

For a minor performance increase you can copy this configuration to your virtual host configuration if you're using apache.

Is it possible to install The Bug Genie on systems with pcre libs < 8?  

No. Our intelligent text parser uses syntax introduced in pcre version 8, and will not function properly in earlier versions. Upgrading pcre libraries can be quite painful, so you should look for packages for your distribution (if running unix/linux).

Will you support older versions of PHP, such as 5.3.x or 5.6.x?  

No. We will not add support for any versions of PHP earlier than the specified required minimum version.

Is it possible to install The Bug Genie on IIS6?  

The Bug Genie requires url rewriting to function. You will be able to install it without, but you will not be able to use The Bug Genie without an url rewriting module properly configured for The Bug Genie. There is a free rewrite module available from microsoft's codeplex: http://iirf.codeplex.com/ and there is also one available from a company called helicontech: http://www.helicontech.com/isapi_rewrite/

Tips and tricks about installing The Bug Genie on IIS6 can be found in this forum thread:
http://www.thebuggenie.com/forum/viewtopic.php?f=5&t=646

Troubleshooting  

Error: uasort() expects parameter 2 to be a valid callback, no array or string given when using eAccelerator  

This is a conflict with The Bug Genie and eAccelerator. See issue #2115 for more information and workarounds.

Error: date(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function.  

The Bug Genie requires php to be correctly configured - this includes configuring the default timezone. As The Bug Genie supports multiple timezones including server / user difference, this is a requirement for The Bug Genie to function properly. Please see the php documentation for how to set this up properly: http://www.php.net/manual/en/datetime.configuration.php#ini.date.timezone

Error: preg_match() function.preg-match: Compilation failed: unrecognized character after (?< at offset  

The Bug Genie requires pcre libraries version 8 or later. This message usually occurs if the pcre libraries on your system is older than the required version. (On many !CentOS and !RedHat systems, the installed libraries are version 6.x) You can find your installed pcre library version by looking at the pcre section of your

<?php
 phpinfo();

To fix this error you need to upgrade your system pcre libraries to a new version, at least version 8.

Note: as of 3.1, a check is performed during installation to make sure your pcre libraries are up to date. Installation will not be possible with pcre libraries < version 8.

Configuration and general usage  

What is the default username and password?  

The Bug Genie sets up one administrator and one (automatic) guest user. The Administrator user has the following username/password:

• Username: administrator
• Password: admin

It is recommended that you change this immediately after logging in for the first time, to avoid unwanted access. Remember that the initially created administrator user has all the necessary permissions to perform common tasks, such as configuring The Bug Genie, adding users, teams, groups, projects, etc.

Which web browsers are supported?  

In general, we recommend that you use the latest available version of your web browser of choice. The Bug Genie tries to use standards compliant markup and features wherever possible, but in some cases certain UI features or functionality may not be available for your browser yet. There are also some browsers we know works to some degree, and there are some browsers we will not make an effort supporting. In general, the supported browser versions are the evergreen browsers.

Browsers known to not function adequately:

• Internet Explorer
• Rekonq
• Konqueror
• Qupzilla
• Firefox 3.x

Where is the "I forgot my password" link?  

To send out a forgotten password message, the email functionality must be set up and enabled, otherwise there would be no way to actually email users the password restoration instructions. When this functionality is enabled and configured, a "Forgot password" link is available in the login / registration popup.

Can I customize the text above the login box?  

Yes. The text for this box is stored as a Wiki page, and can be accessed by editing the LoginIntro article in the main wiki in your installation.

How do I set up The Bug Genie to use GMail / Google Mail to send out email notifications?  

You need to use special settings for GMail / Google Mail to work properly. For this to work, PHP needs to have the openssl extension installed and enabled. To use GMail / Google Mail to send out email notifications, make sure these settings are correctly configured:

• SMTP server address: ssl://smtp.gmail.com
• SMTP address port: 465
• SMTP username / password: your gmail address and password
• Email «from»-address: your gmail address

Development  

Where can I download the latest version?  

For details on accessing our git repositories or getting started on developing with thebuggenie, see the Developer's Guide getting started guide.