To get started as developer or contributor to the Elentra Platform you are required to have:
An active GitHub.com account
An approved Elentra Contributor Agreement
A suitable developer workstation
You should also be setup with:
Access to our Slack Team at https://elentra.slack.com and the #developers
channel
Access to our Jira tracker at https://elentra.atlassian.net
Subscription to our developer-l@elentra.org and community-l@elentra.org mailing lists
While this documentation is intended to get you up and running as quickly as possible, you may still run into unforeseen corners of the stack. If you have questions then please reach out to us on Slack or the Developer mailing list. We won't bite.
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.
You must have two-factor authentication enabled for your GitHub account in order to join the ElentraProject
GitHub organization.
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.
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.
Please note that this video is slightly out-of-date, but is still useful. @todo
The elentra-developer
Docker environment is a lightweight, developer-friendly, virtualization layer that should be used to provide a local development environment that closely mimics your production Elentra environment.
While you could install and configure your own local version of Apache, MariaDB, and PHP, this Docker environment is intended to expedite the setup process for most developers.
Please note that you really only need to install one per category listed below.
Category | Software | macOS | Windows | Linux |
Virtualization | ​Docker Desktop​ | X | X | X |
SCM | ​Git​ | X | X | X |
Git Client | ​SourceTree​ | X | X | ​ |
Git Client | ​GitKracken​ | X | X | X |
MariaDB GUI | ​Sequel Ace​ | X | ​ | ​ |
MariaDB GUI | ​DBeaver​ | X | X | X |
IDE | ​PhpStorm​ | X | X | X |
API Client | ​Postman​ | X | X | X |
Visual Diff | ​Araxis Merge​ | X | X | ​ |
Visual Diff | ​Meld Merge​ | X | X | X |
Text Editor | ​Visual Studio Code​ | X | X | X |
Diagram Designer | ​DbSchema​ | X | X | X |
Make sure that you have completely installed the Highly Recommended Software Stack listed above, otherwise a lot of this won't make sense.
Warning: This step can be painful to explain to new developers, so please bear with us. On the plus side it will eventually go away thanks to a not-yet-approved RFC standard that has already been adopted by Google Chrome.
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 (e.g., medtech-1x-me.localhost
).
# Elentra Platform127.0.0.1 elentra-1x-admissions.localhost127.0.0.1 elentra-1x-cpd.localhost127.0.0.1 elentra-1x-me.localhost
sudo vim /etc/hosts
As an Administrator open C:\Windows\System32\Drivers\etc\hosts
with Notepad.
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.
If you run ssh git@github.com
from within Terminal or Git Bash and it fails to authenticate with GitHub, then you have a problem.
Please make sure your SSH Public Key (~/.ssh/id_rsa.pub
) has been added to GitHub's SSH and GPG keys section before proceeding.
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.
Are you running Windows 10? Before you clone our repositories you must disable Git's autocrlf feature for automatically converting line endings. If you don't do this, your container will not start successfully.
Run the following within Git Bash:
git config --global core.autocrlf false
The following documentation utilizes elentra-1x-me as an example, but elentra-1x-me can be replaced with either elentra-1x-admissions or elentra-1x-cpd depending on your need.
Using either Terminal or Git Bash on your host desktop, clone the elentra-developer
Git repository into a folder within your home directory (e.g., ~/Documents
).
cd ~/Documentsgit 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 ~/Sitescd ~/Sitesgit clone git@github.com:ElentraProject/elentra-1x-me.git
Optionally, clone the Elentra API repository into the same directory:
cd ~/Sitesgit clone git@github.com:ElentraProject/elentra-1x-api.git
Start the Elentra Developer Docker environment by running the developer setup command within the elentra-developer
Docker directory:
cd ~/Documents/elentra-developer./developer setup
cd ~/Documents/elentra-developer./developer.bat setup
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:
# Primary container:docker exec -it elentra-developer bash​# Supporting containers:docker exec -it elentra-mariadb bashdocker exec -it elentra-redis bashdocker exec -it elentra-phpmyadmin bash
The following directories are automatically mapped for you in elentra-developer
:
Host Directory | Container Directory |
|
|
|
|
|
|
|
|
Are you running Windows 10? Unfortunately, you're going to have an issue with that last one. To work around this Windows permissions issue you will need execute the following commands within the container bash shell:
docker exec -it elentra-developer bash​rm /root/.ssh/id_rsacp /run/secrets/ssh_private_key /root/.ssh/id_rsachmod 0400 /root/.ssh/id_rsa
If you are not using our Docker environment make sure that:
Your development environment meets the System Requirements​
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';
You have configured your Apache installation with the appropriate local virtual hosts.
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...
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 bashcd /var/www/vhosts/elentra-1x-megit checkout developgit 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 bashcd /var/www/vhosts/elentra-1x-metouch 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-apigit checkout -- composer.lock
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​
​Deployer provides a consistent and reliable methodology that lets you deploy and roll-back new releases to your servers from your command line or from a CI/CD server.
These instructions assume that you are running the Elentra Developer Docker Environment, and that you have a fully functional Branded Edition cloned to your ~/Sites/
directory.
Elentra Developer Docker Environment
# Connect to the shell within elentra-developer.docker exec -it elentra-developer bash​# Change to your Branded Edition directory.cd /var/www/vhosts/ys-elentra-1x-me/deployment​# To deploy to staging (i.e., deploy the ys/staging branch):dep deploy staging​# To deploy to production (i.e., deploy the ys/production branch):dep deploy production​# To rollback to the previous release:dep rollback production