# Exchange 2.0
Credebt Exchange ® Online Trading Software Project

## Requirements:
* Apache 2.x
* PHP >= 5.3 && PHP <= 5.6 (with Apache 2 mod_php)
* MySQL >= 5.5 && MySQL <= 8.0 (or MariaDB equivalent)

# Environments

## Local Development Environment
* Clone branch to a local working directory
* Navigate to configuration directory and copy (or create a symbolic link) the local configuration file `local.php` to `default.php`, i.e.: `cd exchange/config; cp local.php default.php` or `cd exchange/config; ln -s local.php default.php`
* Ensure that URLs, database access credentials and storage directories are correctly setup in the default configuration file
* Install a local instance of: Apache 2.x web server software (with PHP >= 5.3 && PHP <= 5.6 mod_php module enabled)
* Ensure that Apache virtual host configuration for the local site provides access to the following app folders: `cmws`, `eui`, `exchange`, `sfws`. This can either be configured by setting the cloned working directory as `DocumentRoot` or by creating an `Alias` for each of the required directories. 

## Dev Environment
* Commit new software changes to the `dev` GitHub branch using a Pull Request from a custom development branch
* Navigate to GitHub `Actions` and inspect the results of `Dev CD` auto deployment workflow. AWS CodeDeploy Agent software (that is installed directly on the `Exchange2-Dev` EC2 instance) also generates a deployment log file. The location of the log file is: `/var/log/aws/codedeploy-agent/codedeploy-agent.log`.
* Access the BackOffice UI on the Dev intance of the application using this link: `https://ex2dev.credebt.com/exchange/admin`

## Staging Environment
* Commit new software changes to the `staging` GitHub branch using a Pull Request from a development branch
* Navigate to GitHub `Actions` and inspect the results of `Staging CD` auto deployment workflow. AWS CodeDeploy Agent software (that is installed directly on the `Exchange2-Staging` EC2 instance) also generates a deployment log file. The location of the log file is: `/var/log/aws/codedeploy-agent/codedeploy-agent.log`.
* Access the BackOffice UI on the Staging intance of the application using this link: `https://ex2staging.credebt.com/exchange/admin`

## Production Environment
* Commit new software changes to the `main` GitHub branch using a Pull Request from the `staging` branch
* Navigate to GitHub `Actions` and inspect the results of `Production CD` auto deployment workflow. AWS CodeDeploy Agent software (that is installed directly on the `Exchange2-Production` EC2 instance) also generates a deployment log file. The location of the log file is: `/var/log/aws/codedeploy-agent/codedeploy-agent.log`.
* Access the BackOffice UI on the Production intance of the application using this link: `https://www.credebtexchange.com/exchange/admin`

## Software Deployment

The software deployment for `dev`, `staging` and `main` GitHub branches is fully automated using AWS CodeDeploy and GitHub Actions features.
When a "Push" event occurs in GitHub `dev`, `staging` or `main` branch, the following GitHub Actions worfklows are executed:
* For `dev` branch: `Dev CD` worfklow deploys the software to `Exchange2-Dev` EC2 instance
* For `staging` branch: `Staging CD` worfklow deploys the software to `Exchange2-Staging` EC2 instance
* For `main` branch: `Production CD` workflow deploys the software to `Exchange2-Production` EC2 instance

Continous Deployment GitHub Actions are configured to use specific Deployment Groups that are configured in AWS Developer Toos -> CodeDeploy console.
* For `Dev CD` deployment workflow, `Exchange2.0-DevGrp` is used
* For `Staging CD` deployment workflow, `Exchange2.0-StagingGrp` is used 
* For `Production CD` deployment workflow, `Exchange2.0-ProductionGrp` is used

GitHub Actions access to the AWS CodeDeploy features is setup using the `github-actions` AWS user account.

### Installation Directory
For Dev, Staging and Production instances of Exchange 2.0 software, the default app intallation directory on EC2 server is: `/www/exchange2`

### Deployment Hooks
The automated software deployment process involves a number of different hooks. These are configured in the default AWS CodeDeploy configuration file: `appspec.yml`
* ApplicationStop: `scripts/stop-server.sh` is used to stop the Apache web server process
* BeforeInstall: `scripts/backup-revision.sh` is used to backup the existing revision fileset and clean the installation directory
* AfterInstall: `scripts/after-install.sh` is used to link the default configuration file relevant to the specific environment and change the permissions of the application files
* ApplicationStart: `scripts/start-server.sh` is used to start the Apache web server process
* ValidateService: `scripts/check-server.sh` is used to verify if Apache web server process started successfully

### Revision Backup
Each time a new revision is auto-deployed to the EC2 server, a previous revision fileset is archived and moved to a backup directory. The location for the fileset backups is as follows:
* For Dev instance: `/newvolume/backup/apps/dev`
* For Staging instance: `/newvolume/backup/apps/staging`
* For Production instance: `/newvolume/backup/apps/production`

### Production to Dev and/or Staging dataset import
Steps to import a fresh (or specific archived) dataset from a production database backup:
* On `Exchange2-Production` EC2 instance, create an on demand database backup SQL file: `mysqldump -u root -p --quick --max_allowed_packet=512M --compress --databases exchange | gzip > exchange-sample-dataset.sql.gz` and move the backup file into the following folder: `/newvolume/backup/db/misc`
* On `Exchange2-Dev` or `Exchange2-Staging` EC2 instance, copy the SQL backup archive file from `/newvolume/backup/db/misc` to a local temporary folder (alternatively take one of the existing backup files located in the backup directory: `/newvolume/backup/db`)
* Extract the SQL file from the archive: `gunzip exchange-sample-dataset.sql.gz`
* Edit the SQL file: `vim exchange-sample-dataset.sql`, replace the name of the existing database `exchange` with the name of the dev or staging database: `exchange_dev` or `exchange_staging` and save the changes
* Import the modified SQL file to the Dev or Staging database server (ensure to execute the import command on `Exchange2-Dev` or `Exchange2-Staging`  EC2 instance): `mysql -u root -p exchange_dev < exchange-sample-dataset.sql` or `mysql -u root -p exchange_staging < exchange-sample-dataset.sql`