• This is an implementation of the web frontend for Student StarCraft AI Tournament (SSCAIT): http://sscaitournament.com/
• It is normally used in conjunction with SSCAIT Tournament Manager from this repository: https://github.com/certicky/sscait-tournamentmanager
• This web frontend should typically be hosted on the Host machine of SSCAIT Tournament Manager, where its database also runs (see https://github.com/certicky/sscait-tournamentmanager).
• Warning: This implementation is a complete spaghetti code mess. It's a hack on top of a hack and quick patch on top of a quick patch. None of this was designed to be used for more than one semester, yet here we are, over 12 years later, still running it. Fun!

Fig.1: Project Architecture Diagram

• Note: to see more detailed instructions based on these instructions that record the necessary/notable installation instructions that I used for a new web server host while I migrated the website from a different hosting company, see INSTALL.txt.
• Install web server of your choice (e.g. Apache) and PHP 7 or newer compatible version. PHP 8.3 or 8.2 seem to work. Ensure that php-zip is installed. Ensure that MySQL Server and php-mysql and the mysqlnd PHP extension is installed.
• Install composer. This is used for downloading some dependencies.
• Make sure you have MySQL server up and running and that it contains the sc database and a user with all the required privileges.
  • You should already have the DB set up if you're using this in conjunction with https://github.com/certicky/sscait-tournamentmanager.
  • If you don't have the DB set up yet, create it and then run the database.sql to create required tables.
• Clone this repository and update your webserver's settings so that the www/index.php from the repo is served by it.
• Make a copy of settings_server.php.template to the www folder and name it settings_server.php. Update the values inside like this:
  • $GLOBALS['ADMIN_EMAIL']: email address to which the emails for the attention of SSCAIT server administrators are sent. Note that this address will be visible on the SSCAIT website.
  • $GLOBALS['DOMAIN_WITHOUT_SLASH']: if and when you've done the necessary setup to allow the website to work via HTTPS (e.g. "https://sscaitournament.com" works in a browser), to protect privacy (e.g. user passwords, user email addresses, and traffic in general), you should preferably edit just the http: part and change it to https: to force links within the website to use HTTPS, otherwise you can leave this setting alone. Similarly, if you disable HTTP access entirely or forcefully redirect all HTTP traffic to HTTPS, you should also change just the http: part to https:.
  • $GLOBALS['PROJECT_FOLDER_WITHOUT_SLASH']: folder containing the project files. Warning: there should not be a path to this directory within the directory (or directories) served by your webserver, because some files and folders such as composer.json, composer.lock, vendor/ should not be exposed by the website.
  • $GLOBALS['BOTS_FOLDER_WITHOUT_SLASH']: folder containing the bots files - part of the set up of SSCAIT Tournament Manager. Warning: there should not be a path to this directory within the directory (or directories) served by your webserver, otherwise everyone could download files from every bot's read and write folders etc without logging in.
  • $GLOBALS['REPLAYS_FOLDER_WITHOUT_SLASH']: folder containing the saved replay files - part of the set up of SSCAIT Tournament Manager. Note: if there is no path to this directory within the directory (or directories) served by your webserver at relative path Replays, links in web pages to replay files won't work. E.g. if the directory is /var/www/html/Replays it would work.
  • $GLOBALS['CACHE_FOLDER_WITHOUT_SLASH']: folder reserved for data caching - just create an empty folder and give web server user the read & write permissions.
  • $db_host, $db_username, $db_password: database credentials. Warning: to include a single quote character (') or backslash character (\) in e.g. the $db_password field (or any of the other fields in this file), each occurrence must be prefixed by a backslash character, e.g. \' or \\. Other characters (e.g. " or $) don't need special handling.
  • $GLOBALS['SMTP_*']: credentials for whatever external SMTP service we're using to send emails to bot authors and to admin (e.g. Gmail or https://www.sendinblue.com/). Currently, it supports sending emails from a Gmail account using the Gmail API via the XOAUTH2 mechanism, which requires using Google Developer Console to generate a Google Client ID and Google Client Secret to configure in the settings in this file (note: Google Refresh Token will be configured later in these instructions). FYI, the website uses PHPMailer. I got the mechanism working in the website by following the instructions at https://web.archive.org/web/20231208220838/https://artisansweb.net/how-to-send-email-using-gmail-api-with-phpmailer/, except I didn't do the "Under Authorized JavaScript origins enter your domain URL" part or the parts about storing the result in a database or the "Before running this file, make sure you have passed your client ID and client secret to the variables $clientId and $clientSecret respectively" part. Look at that page to see instructions for what you need to do in Google Developer Console (and also see the instructions later below).
  • $GLOBALS['loggingInEnabled']: you might want to temporarily set this to false, until you're ready to test that the website can send emails, otherwise people might try to register on the website but might not receive any emails, and errors might appear in log files.
• Change the working directory to $GLOBALS['PROJECT_FOLDER_WITHOUT_SLASH'] then run composer to download the dependencies phpmailer/phpmailer and league/oauth2-google (which are necessary for the website to send emails using the Gmail API), e.g.:
  • cd /var/www/sscait-web/
  • composer require phpmailer/phpmailer
  • composer require league/oauth2-google
  • Note: get_oauth_token.php currently uses a hardcoded path to under /var/www/sscait-web/ - if you are using a different path, edit the path in get_oauth_token.php.
• By default, PHP might not allow large files to be uploaded. You might need to increase the post_max_size and upload_max_filesize settings in php.ini, e.g. post_max_size = 101M and upload_max_filesize = 100M, to enable users to upload a bot ZIP file up to 100 MB size.
• If everything went well, the web should be accessible at a location determined by your web server - usually http://localhost/ or http://localhost:8080.
• In order to find out what Google Refresh Token to configure in settings_server.php in order for the website to be able send emails, the website needs to be reachable at the Redirect URI you've configured in Google Developer Console (e.g. https://sscaitournament.com/get_oauth_token.php). To generate a Google Refresh Token for the first time, or generate another one after the old one has expired or after you've revoked it, open https://sscaitournament.com/get_oauth_token.php in a browser, select "Google" provider, enter the Google Client ID and Google Client Secret, then press the "Continue" button. It should show a sign-in page. Use the page to log in to the account specified by $GLOBALS['SMTP_USERNAME']. It should ask for permission to access the account, so grant the permissions. If successful, it should display the Google Refresh Token and associated expiry information. Warning: it will only display the Google Refresh Token the first time you do it, so be sure to capture it, otherwise you would need to revoke the Google Refresh Token in Google Developer Console then try again, or wait for it to expire. If it ever expires, you'll need to (manually) use the https://sscaitournament.com/get_oauth_token.php page again to get another one, but the one I got expires in over 50 years. Configure $GLOBALS['SMTP_GOOGLE_REFRESH_TOKEN'] in settings_server.php, and ensure that $GLOBALS['loggingInEnabled'] is set to true. You could try using the website to reset a user's password to test that the website can successfully send emails.
• During initial setup or during development, consider changing the error_reporting setting in php.ini for Apache (e.g. at /etc/php/8.3/apache2/php.ini) from E_ALL & ~E_DEPRECATED & ~E_STRICT to just E_ALL, then consider changing it back for production use.
• Tip: depending on which operating system or webserver or other packages you're using, some relevant log messages might be in the system journal (e.g. run sudo journalctl on Ubuntu to see them, or Event Viewer on Windows) or in files that might be at/under /var/log/mysql/ or /var/log/mysqld.log, /var/log/apache2/ or /var/log/httpd/, and possibly /var/log/php-fpm/. Some example commands to filter for potential problems (e.g. failures due to timeout due to the machine being overloaded) might include:
  • On e.g. Ubuntu, filter out some journal messages for the current boot that seem to simply be failed hacking attempts or web user disconnections, and display all other errors/warnings: sudo journalctl -b 0 -p 0..4 | grep -v -e ": error: kex_exchange_identification: read: Connection reset by peer"$ -e ": error: kex_protocol_error: type [23]0 seq [1-7] [[]preauth[]]"$ -e ": fatal: userauth_finish: send failure packet: Connection reset by peer [[]preauth[]]"$ -e ": error: Protocol major versions differ: 2 vs. 1"$ -e ": fatal: userauth_pubkey: parse publickey packet: incomplete message [[]preauth[]]"$ -e ": error: maximum authentication attempts exceeded for invalid user " -e ": error: maximum authentication attempts exceeded for root from " | less
  • sudo cat /var/log/mysql/error.log | grep -v " \[System\] " | less
  • sudo cat /var/log/apache2/error.log | grep -v "[:]\(debug\|notice\|info\)" | grep -v -e " \(AH01797\|AH01630\): client denied by server configuration: " -e " AH10244: invalid URI path " -e " AH01276: Cannot serve directory .*: No matching DirectoryIndex .* found, and server-generated directory index forbidden by Options directive" | less
  • sudo cat /var/log/apache2/access.log | less to see the details of every request. I also added some extra columns to each LogFormat in /etc/httpd/conf/httpd.conf, e.g. %T (the time taken to serve the request, in seconds) and port:%p (the canonical port of the server serving the request, e.g. 80 (the default port number for HTTP) or 443 (the default port number for HTTPS)). If you add the %T column, you can use e.g. grep or awk/gawk to filter on requests that have a high time taken to serve the request, and possibly failed due to timeout.
  • sudo cat /var/log/mysqld.log | grep -v " \[Note\] " | less
  • sudo cat /var/log/php-fpm/www-error.log | grep -v " PHP Notice: " | less
  • sudo cat /var/log/php-fpm/error.log | grep -v " NOTICE: " | less
  • sudo cat /var/log/httpd/error_log | grep -v "[:]\(debug\|notice\|info\)" | grep -v -e " \(AH01797\|AH01630\): client denied by server configuration: " -e " AH10244: invalid URI path " -e " AH01276: Cannot serve directory .*: No matching DirectoryIndex .* found, and server-generated directory index forbidden by Options directive" | less
  • sudo cat /var/log/httpd/access_log | less to see the details of every request. I also added some extra columns to each LogFormat in /etc/httpd/conf/httpd.conf, e.g. %T (the time taken to serve the request, in seconds) and port:%p (the canonical port of the server serving the request, e.g. 80 (the default port number for HTTP) or 443 (the default port number for HTTPS)). If you add the %T column, you can use e.g. grep or awk/gawk to filter on requests that have a high time taken to serve the request, and possibly failed due to timeout.
  • sudo cat /var/log/httpd/ssl_error_log | less