BCOE&M 2.7.0: Installation Instructions

These instructions are for those who wish to set up BCOE&M on their own web server. Hosted installations follow a different procedure outlined in a setup email subscribers receive after paying for the service.

Step 1: Verify PHP and MySQL Versions

BCOE&M has been tested with PHP versions 5.3.X (and above) and 7.3.X as well as MySQL version 5.5.X.

If you plan on installing on a local server, we recommend downloading and installing Xampp for your operating system. Xampp, a PHP development environment from Apache Friends, contains the correct versions of PHP and MySQL (via MariaDB) for use with BCOE&M.

Step 2: Verify PHP Extensions

BCOE&M utilizes a number of PHP extensions that must be enabled for the application to function properly. All but OpenSSL are enabled by default with a normal PHP server installation. Check with your web host to verify that the following are enabled:

Step 3: Create a MySQL Database

  1. Create a database on your web server. The methodology for creating a database varies from hosting provider to hosting provider, so be sure to consult your provider’s documentation.
  2. Add a user to the database you just created with a secure password. This is usually done via your webserver’s control panel.

Refer to your web hosting provider's documentation for procedures specific to their environment.

Step 4: Required Configuration

  1. Unzip/unarchive the source code package you downloaded from GitHub.
  2. With your favorite text editor (Sublime Text, Notepad++, even plain ’ol Notepad, etc.), open the the config.php file located in the /site/ directory.
  3. Generally, the $hostname variable does not need to be changed from "localhost" - however, some server enviornments may specify something different. Be sure to consult your hosting company's documentation for connecting to MySQL databases.
    1. For GoDaddy users, changing this variable is necessary. Consult this GoDaddy help article for details.
  4. Define the $username, $password, and $database variables.
  5. Optionally, define the $prefix variable. This is useful if you wish to have separate BCOE&M installations or other applications share the same mySQL database.
  6. Optionally, define the $installation_id to provide a unique ID for this BCOE&M instance.
    1. If you plan on running multiple instances of BCOE&M from the same domain, you'll need to give each installation a unique identifier. This prevents "cross-pollination" of session data display.
  7. Optionally, change the $session_expire_after value. Default is 30 minutes.
  8. If you are installing the application in a sub-folder (e.g., http://www.yoursite.com/subfoldername/), be sure to define the $sub_directory variable.
    1. Note that you will need to alter the .htaccess file as well if using a subfolder. Directions to accomplish this are contained in that file.
  9. Make sure the $setup_free_access variable is set to TRUE.
    1. For security reasons, after finishing setup, be sure to change TRUE back to FALSE and re-upload the /sites/config.php file to your server.

A sample of the configured variables is provided below (the commented lines have been removed to save screen space). This exemplifies an installation that is housed in a sub-folder with a DB table prefix, installation ID, and a 45 minute session timeout. Leave the $sub_directory variable empty if you are not installing in a subfolder – $sub_directory = "";.

     * Configuration for an installation housed in a sub-folder with a DB
     * table prefix, installation ID, and a 45 minute session timeout.
    $hostname = "localhost";
    $username = "mycleverusername";
    $password = "mysecurepassword";
    $database = "bcoem";
    $connection = new mysqli($hostname, $username, $password, $database);
    $brewing = $connection;
    $images_dir = dirname( __FILE__ );
    $prefix = "bcoem_";
    $installation_id = "84972da38Nza39124";
    $session_expire_after = "45";
    $setup_free_access = TRUE; // Change to FALSE after setup is completed
    $sub_directory = "/comp";
    $base_url = "http://".$_SERVER['SERVER_NAME'].$sub_directory."/";
    $server_root = $_SERVER['DOCUMENT_ROOT'];

Step 5: Set Global Definitions and Options

Via the the /site/paths.php file, there are a few ways for administrators to further customize their installations, take it offline for maintenance, and enable troubleshooting functions. Open that file and enable or disable the global definitions housed there (mark them TRUE or FALSE). Each global definition is detailed below.

Maintenance Mode

Set define('MAINT', TRUE); to bypass the default home page and display a "Site in Maintenance" message to visitors. Default is FALSE.


Set define('CDN', TRUE); to utilize CDNs (Content Delivery Networks) that house essential code libraries such as Bootstrap, jQuery, TinyMCE, Font Awesome, etc. The default value of TRUE should be good for the majority of installations. However, some web hosts do not play well with CDN and/or response is delayed from a CDN provider. If this is the case, follow the directions detailed in the Load Libraries Locally page and then set the value to FALSE. Default value is TRUE.


Set define('TESTING', TRUE); to put your installation into test mode. Especially useful when testing outside functions such as PayPal IPN. Default is FALSE.


If your site is experiencing functionality issues, set define('DEBUG', TRUE); to display all PHP errors on screen. Especially useful if you're getting the "white screen of death." These errors are essential for diagnosing a problem if you report an issue on GitHub. Default value is FALSE.

To view the session variables BCOE&M employs, set define('DEBUG_SESSION_VARS', TRUE);. This will show a collapsable table of all session variables on screen. Default is FALSE.

Force Update

Set define('FORCE_UPDATE', TRUE); if your installation is experiencing certain MySQL-related errors such as column does not exist, etc. This will trigger database structure checks and add or remove columns that may be throwing errors. Default value is FALSE.

Only enable this definition for a single refresh of the home page. Otherwise, the script will run on every page access until disabled, significantly affecting performance and page-load.

Enable Markdown

Markdown is a standard that employs plain-text syntax for text formatting which is then converted to structually valid HTML for display. This is useful if your web host employs a strict security protocol that disallows HTML tags in http POST methods and you are unable to update your competition information.

Set define('ENABLE_MARKDOWN', TRUE); to use Markdown syntax instead of HTML for text formatting. This will swap the TinyMCE editor for the Bootstrap Markdown editor - used in BCOE&M's Competition Preparation > Edit Competition Info function and store formatted text as plain text in your database. Default value is FALSE.

Enable PHPMailer

BCOE&M employs several email-related functions such as sending account creation confirmations and contacting competition officials, relying on PHP's native mail() function. In some web hosting environments, mail() is disabled, thereby disabling all email functions from the application. If that is the case in your environment, or if you simply wish to use SMTP protocols to send emails, set define('ENABLE_MAILER', TRUE);. This will enable the use of PHPMailer to send emails from the application.

Please Note: Further configuration is necessary in the /site/config.mail.php file for PHPMailer to work. See the configuration documentation in that file for more information.

Step 6: Upload Files

  1. Using your favorite FTP program, upload the entire contents of the source code folder (including your customized /sites/config.php file) to your web server.
  2. Once that is done, you can now set up your installation.

Step 7: Set Up

  1. Browse to your installation's web address.
  2. You’ll be taken through a series of steps to customize the setup of your installation. DO NOT SKIP THESE STEPS. Vital information is collected that optimize the installation's behavior and display of data.
  3. That’s it! You can now browse to your installation's address, further customize it, and/or distribute the web address to begin collecting participants and their associated entries.
  4. Enjoy your favorite homebrewed beverage. You’ve earned it.

Setup Issues?

There are various reasons why the browser-based setup may not be successful. Below are some troubleshooting steps to take.

Check PHP and MySQL Versions

BCOE&M 2.7.0 has been tested with PHP version 5.6.X (up to 7.3.X) and MySQL 5.5.X. Make sure you have these versions installed on your webserver.

How do you check your server’s PHP and MySQL version? Simple, use the phpinfo() function.

  1. Create a new blank document in your favorite text editor. Name it php_info.php or similar.
  2. Add the following code to the blank document: <?php echo phpinfo(); ?>
  3. Upload the file to your BCOE&M’s installation root folder.
  4. Browse to the file (e.g., http://www.yoursite.com/php_info.php) and take a look at the results. Specifically, look for the following sections:
    1. PHP Version - should be at least 5.4.X but no later than 7.3.X
    2. mysqli - should be at least 5.5.X
    3. session - Session Support should be enabled
  5. PHP's Fileinfo extension must be enabled. If it is not, check the PHP Manual for installation instructions.
  6. Be sure to remove the php_info.php file once you have determined your environment's configuration settings.

Blank Screen

If you encounter a blank screen during the setup process, first, make sure that you have the correct PHP version installed on your webserver. Previous versions do not handle session instantiation effectively for BCOE&M.

If you have verified that your PHP version is correct, the next step would be to perform a “Fallback Installation” - see below.

Fallback Installation (Non-Browser-Based)

It is possible to install an instance of BCOE&M without using the browser-based installation process.

Included in the package download is a subfolder called “sql” that contains an SQL file called bcoem_baseline_2.1.X.sql. This file contains the complete database structure and dummy data to get you up and running. Complete instructions are at the top of the file.

To install the baseline database and dummy data, you will need access to your database via phpMyAdmin or shell access.