Becoming a Contributor

To get started as developer or contributor to the Elentra Platform you are required to have:

1. An active GitHub.com account

2. An approved Elentra Contributor Agreement

3. A suitable developer workstation

You should also be setup with:

1. Access to our Slack Team at https://elentra.slack.com and the #developers channel

2. Access to our Jira tracker at https://elentra.atlassian.net

3. Subscription to our developer-l@elentra.org and community-l@elentra.org mailing lists

Register with GitHub

If you do not already have an account on GitHub.com, or you would like a separate work-specific account, then please visit https://github.com and sign up for a new account.

Regardless of whether you would like to use your existing account or create a new one, it is important that you know your correct GitHub.com username and that have you provided your full name within the Your Profile > Settings section on GitHub. Failure to do this may result in delays of approval.

Sign the Elentra Contributor Agreement

Before gaining access to our source code repositories you must complete, sign, and submit an Elentra Contributor Agreement. This agreement provides fall-back legal protection for the Elentra Consortium relating to any potential contributions you may make.

Please submit your signed Contributor Agreement with your correct GitHub.com username via e-mail to cla@elentra.org. Once your contributor request has been approved you will receive an invite from GitHub.com to join the ElentraProject organization.

If we have not responded to your contributor request within 1 business day, or if there is an urgent request, please feel free to contact Matt Simpson directly for follow-up.

Your Developer Workstation

While there is no required workstation configuration for Elentra Platform development, there are a number of technologies used by Elentra Consortium developers that dramatically increase productivity and reliability, and promote consistency. The vast majority of these applications are available for macOS 10.10.3+, Windows 10+, and Linux workstations.

Workstation Setup Tutorial

Docker

The elentra-developer Docker container is a lightweight, developer-friendly, virtualization layer that can be used to provide a local environment that closely mimics your production Elentra environment. While you can install and configure your own local version of Apache, MariaDB, and PHP, this Docker container is intended to expedite the setup process for most Elentra developers.

Ensure that you have installed the latest version of Docker for your environment:

• ​Docker Community Edition (full list of environment options)

  • ​Docker for Mac​

  • ​Docker for Windows​

  • ​Docker for CentOS​

  • ​Docker for Ubuntu​

Highly Recommended Software Stack

Installing Elentra

Prerequisites

1. Install the software stack

Make sure that you have completely installed the Highly Recommended Software Stack listed above, otherwise a lot of this won't make sense.

2. Configure your hosts file

While Google Chrome will automatically route *.localhost DNS requests to your local host, other supported browsers such Firefox, Edge, and potentially Safari may not.

You should add the following Elentra Platform hostnames to your hosts file, and potentially other Branded Edition hostname's as well (i.e. medtech-1x-me.localhost).

# Elentra Platform
127.0.0.1   elentra-1x-admissions.localhost
127.0.0.1   elentra-1x-cpd.localhost
127.0.0.1   elentra-1x-me.localhost

macOS / Linux: Using sudo open /etc/hosts with your favorite text editor.

sudo vim /etc/hosts

Windows: As an Administrator open C:\Windows\System32\Drivers\etc\hosts with Notepad.

3. Create an SSH key and add it to GitHub

If you do not already have an SSH key on your workstation and added to your GitHub profile, then please do this before you go any further.

Using either Terminal or Git Bash on your host desktop, run ssh-keygen. The defaults that are provided by ssh-keygen should be fine, including the default ~/.ssh/id_rsa storage location and an empty passphrase.

Once you have created your new SSH key, you must add your SSH Public Key (~/.ssh/id_rsa.pub) to your GitHub profile in the SSH and GPG keys section.

Clone from GitHub

The Elentra (Admissions, ME, and CPD) source code can be obtained via Git source control management from GitHub once your access request has been granted.

Using either Terminal or Git Bash on your host desktop, clone the elentra-developer Git repository into the Documents folder within your home directory. If this directory does not exist, simply create it:

mkdir ~/Documents
cd ~/Documents
git clone git@github.com:ElentraProject/elentra-developer.git

Using either Terminal or Git Bash on your host desktop, clone the Elentra Git repository into the Sites folder within your home directory. If this directory does not exist, simply create it:

mkdir ~/Sites
cd ~/Sites
git clone git@github.com:ElentraProject/elentra-1x-me.git

Optionally, clone the Elentra API repository into the same directory:

cd ~/Sites
git clone git@github.com:ElentraProject/elentra-1x-api.git

Start the Docker Container

Start the Docker container by running docker-compose up -d within the elentra-developer Docker directory:

cd ~/Documents/elentra-developer/docker
docker-compose up -d

That should be it. Installation of the initial container may take a little while, but when it's complete you can connect to the bash shell of your container by typing:

docker exec -it elentra-developer bash

Please note: the following host-to-container locations are automatically mapped for you:

1. ~/Sites to /var/www/vhosts

2. ~/Documents/elentra-developer/docker/elentra/apache/vhosts.d to /etc/httpd/vhosts.d

3. ~/.ssh/id_rsa to /root/.ssh/id_rsa

docker exec -it elentra-developer bash
​
rm /root/.ssh/id_rsa
cp /run/secrets/ssh_private_key /root/.ssh/id_rsa
chmod 0400 /root/.ssh/id_rsa

Not using Docker?

If you are not using our Docker container just make sure that:

1. Your development environment meets the System Requirements​

2. You have created the databases on your host database server, and also created a user account with privileges to these new databases.

   CREATE DATABASE `elentra_auth` CHARACTER SET utf8 COLLATE utf8_general_ci;
   CREATE DATABASE `elentra_admissions` CHARACTER SET utf8 COLLATE utf8_general_ci;
   CREATE DATABASE `elentra_cpd` CHARACTER SET utf8 COLLATE utf8_general_ci;
   CREATE DATABASE `elentra_me` CHARACTER SET utf8 COLLATE utf8_general_ci;
   CREATE DATABASE `elentra_me_clerkship` CHARACTER SET utf8 COLLATE utf8_general_ci;
   CREATE USER 'elentra'@'localhost' IDENTIFIED BY 'password';
   GRANT ALL ON elentra_auth.* TO 'elentra'@'localhost';
   GRANT ALL ON elentra_admissions.* TO 'elentra'@'localhost';
   GRANT ALL ON elentra_cpd.* TO 'elentra'@'localhost';
   GRANT ALL ON elentra_me.* TO 'elentra'@'localhost';
   GRANT ALL ON elentra_me_clerkship.* TO 'elentra'@'localhost';

3. You have configured your Apache installation with the appropriate local virtual hosts.

Authenticate with Private Packagist

Authenticating your elentra-developer Docker container, and possibly your host computer as well, is necessary in order to install the dependencies used by the Elentra Platform.

As of Elentra Admissions 0.9, Elentra ME 1.13, and Elentra CPD 1.1 our Composer dependencies are managed and installed through a commercial service called Private Packagist - https://packagist.com. This service mirrors our dependencies from their original location and provides a reliable, redundant, and consistent dependency source for our deployment processes.

Once you have obtained your Institutional Authorization Token, please run the following command (replacing dcdeef40... with your actual token) within your Docker container:

docker exec -it elentra-developer bash
​
composer config --global --auth http-basic.repo.packagist.com token dcdeef40...

Install the Composer Dependencies

1. Within your elentra-developer Docker container, ensure that you have the develop Git branch checked out and that you are up to date:

 docker exec -it elentra-developer bash
 
 cd /var/www/vhosts/elentra-1x-me
 git checkout develop
 git pull

2. Optionally, if you have cloned the elentra-1x-api repository and want to use this development version instead of the production version, then create a new file named composer-api-dev.json in your elentra-1x-me root directory:

 docker exec -it elentra-developer bash
 
 cd /var/www/vhosts/elentra-1x-me
 touch composer-api-dev.json

Add the following lines to this new composer-api-dev.json file, if you have created one:

 {
       "repositories": [
         {
               "type": "path",
               "url": "../elentra-1x-api",
               "options": {
                 "symlink": true
               }
         }
       ],
       "require": {
         "elentrapackages/elentra-1x-api": "dev-develop"
       }
 }

3. Install the Composer dependencies:

composer install

4. Optionally, to use the local elentra-1x-api, use composer update just for that package and then reset changes to the composer.lock file:

composer update elentrapackages/elentra-1x-api
git checkout -- composer.lock

Proceed to Browser

If all went according to plan you can now visit this local Elentra ME installation using Chrome, Firefox, Safari, or Edge to proceed with the web-based setup: http://elentra-1x-me.localhost​

Deploying Elentra

Capistrano provides a consistent and reliable methodology that lets you deploy and roll-back new releases to your staging and production servers from your command line.

Prerequisites

• Ruby 1.8 or higher

• Ruby Gems 1.3 or higher

• Capistrano 2.15

Installation

Install the Capistrano and a few associated Ruby Gems:

sudo gem install net-ssh -v 4.2.0 --no-ri --no-rdoc
sudo gem install capistrano -v 2.15.9 --no-ri --no-rdoc
sudo gem install colorize --no-ri --no-rdoc
sudo gem install sshkit --no-ri --no-rdoc
sudo gem install gnm-caplock --no-ri --no-rdoc

Please Note: You must install Capistrano 2 (as indicated in the code block above) in order to run the standard Elentra deployment recipes.

Deployment

This example assumes that your deployment directory is located at ~/Sites/elentra-1x-me/deployment. Your deployment recipe exists within the config/deploy.rb directory. Please make sure that this file accurately reflects your hostnames and Git repository location.

To deploy a release, use the terminal and navigate to the deployment directory:

cd ~/Sites/elentra-1x-me/deployment
# deploy to staging
cap staging deploy
# deploy to production
cap production deploy
# rollback to the previous release
cap production deploy:rollback