Elentra Platform Technical Documentation
  • Introduction
  • Reporting Issues
    • Security Notices
  • Administrators
    • Server Requirements
    • Application Server
      • Shibboleth Single Sign-on
      • Installing Supervisor
      • Branded API Setup
      • Installing Mailhog
    • Database Server
  • Developers
    • Getting Started
    • Overview
    • Contributions
      • Request for Change
      • Jira and GitHub Details
      • Coding Standards
      • Quickstart Guide
      • Code Review
    • Database
    • Dataviews for Analytics
    • Global Namespace
    • Elentra ACL
    • Authentication Methods
    • Compatibility Matrix
    • Elentra ME Versions
    • Elentra Settings
    • Elentra Deployment
    • Elentra API
    • Elentra JS
    • Feature Configuration
      • Event Resource Integration
      • Microsoft Teams Integration
    • Troubleshooting & Guides
      • New developer features in Elentra ME 1.22
      • Testing With Codeception
        • Unit Testing
          • Unit Testing Best Practises
          • Writing Unit Testable Code
          • PHPUnit Testing for API
          • PHPUnit Json String Compare Function
        • Functional Testing
          • Functional Testing Best Practices
        • Integration Testing
          • Integration Testing Best Practices
      • Upgrading elentra-developer Docker
      • VS Code Setup
      • Using XDebug in VSCode
      • Upgrading PHP
      • Switching Databases
      • Creating a new virtual host
      • Logging In
      • Composer
      • Curriculum Tag Selector
      • Performance Issues
      • Docker
      • Seed Data Generation
      • Fail Fast Programming
      • Advanced Custom Exception Classes
    • Support
  • Upgrade Guides
    • Upgrading to ME v28.0
    • Upgrading to ME 1.27
    • Upgrading to ME 1.26
    • Upgrading to ME 1.25
    • Upgrading to ME 1.24
    • Upgrading to ME 1.23
    • Upgrading to ME 1.22
    • Upgrading to ME 1.21
    • Upgrading to ME 1.20
    • Upgrading to ME 1.19
    • Upgrading to ME 1.18
    • Upgrading to ME 1.17
    • Upgrading to ME 1.16
    • Upgrading to ME 1.15
Powered by GitBook
On this page
  • Becoming a Contributor
  • Register with GitHub
  • Sign the Elentra Contributor Agreement
  • Your Developer Workstation
  • Docker
  • Highly Recommended Software Stack
  • Installing Elentra
  • Prerequisites
  • Clone from GitHub
  • Start the Docker Environment
  • Authenticate with Private Packagist
  • Install the Composer Dependencies
  • Install the NPM dependencies
  • Proceed to Browser
  • Deploying Elentra
  • Prerequisites
  • Deployment
  1. Developers

Getting Started

PreviousDatabase ServerNextOverview

Last updated 7 months ago

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 and the #developers channel

  2. Access to our Jira tracker at

  3. Subscription to our and 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.

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 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 section on GitHub. Failure to do this may result in delays of approval.

You must have in order to join the ElentraProject GitHub organization.

Sign the Elentra Contributor Agreement

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 Graham Berry 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, Windows 10+, and Linux workstations.

Docker

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 and provide a consistent developer experience across macOS, Windows, and Linux workstations.

Highly Recommended Software Stack

Please note that you really only need to install one per category listed below.

Category

Software

macOS

Windows

Linux

Virtualization

X

X

X

SCM

X

X

X

Git Client

X

X

Git Client ($)

X

X

X

MariaDB GUI

X

MariaDB GUI

X

X

X

Text Editor

X

X

X

API Client

X

X

X

JavaScript Runtime

X

X

X

Visual Diff

X

X

X

Visual Diff ($)

X

X

Diagram Designer ($)

X

X

X

Installing Elentra

Prerequisites

1. Install the software stack

macOS users can enjoy an expedited Highly Recommended Software Stack setup by running the following commands in Terminal:

# 1. Install xCode command line tools:
xcode-select --install

# 2. Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 3. Install Highly Recommended Software Stack
brew install --cask docker \
             sourcetree \
             sequel-ace \
             visual-studio-code \
             postman \
             meld

# 4. Install LTS edition of Node.js via Node Version Manager (NVM).
brew install nvm             
nvm install --lts
             
# 5. Optional Recommended Commercial Software
brew install --cask araxis-merge \
                    dbschema
                    

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 (e.g., medtech-1x-me.localhost).

# Elentra ME Institutional Fork
127.0.0.1   elentra-1x-me.localhost

# Elentra ME Branded Edition
127.0.0.1   ys-elentra-1x-me.localhost

# Elentra Admissions + CPD
127.0.0.1   elentra-1x-admissions.localhost
127.0.0.1   elentra-1x-cpd.localhost
sudo vim /etc/hosts

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 a 4096 bit SSH key on your workstation then you will need to generate one. Using either Terminal or Git Bash on your host desktop, run:

ssh-keygen -t rsa -b 4096

The defaults provided by ssh-keygen should be fine, including the default ~/.ssh/id_rsa storage location and an empty passphrase (providing your workstation is properly secured).

cat ~/.ssh/id_rsa.pub

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.

Clone from GitHub

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

Are you running Windows? 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

Repository #1) Elentra Developer Docker Environment

Using either Terminal or Git Bash on your host desktop, clone the elentra-developer repository into a directory within your home directory (e.g., ~/Documents).

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

Repository #2) Elentra ME

Using either Terminal or Git Bash on your host desktop, clone the elentra-1x-me repository from your Institutional Fork into the ~/Sites directory, and add the Elentra Consortium as an additional Git remote.

mkdir ~/Sites
cd ~/Sites
git clone git@github.com:YourInstitutionalFork/elentra-1x-me.git
cd elentra-1x-me
git remote add consortium git@github.com:ElentraProject/elentra-1x-me.git
git fetch consortium

Repository #3) Elentra API

Next, clone the elentra-1x-api repository into the ~/Sites directory:

cd ~/Sites
git clone git@github.com:YourInstitutionalFork/elentra-1x-api.git
cd elentra-1x-api
git remote add consortium git@github.com:ElentraProject/elentra-1x-api.git
git fetch consortium

Repository #4) Elentra JS

Next, clone the elentra-2x-js repository into the ~/Sites directory:

cd ~/Sites
git clone git@github.com:YourInstitutionalFork/elentra-2x-js.git
cd elentra-2x-js
git remote add consortium git@github.com:ElentraProject/elentra-2x-js.git
git fetch consortium

Start the Docker Environment

Start the Elentra Developer Docker environment by running the developer setup command within the elentra-developer Docker directory:

cd ~/Documents/elentra-developer
./developer 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 bash
docker exec -it elentra-redis bash
docker exec -it elentra-phpmyadmin bash

The following directories are automatically mapped for you in elentra-developer:

Host Directory

Container Directory

~/Sites

/var/www/vhosts

./elentra-developer/resources/services/elentra/etc/httpd/vhosts.d

/etc/httpd/vhosts.d

./elentra-developer/resources/scripts

/root/.bin

~/.ssh/id_rsa

/root/.ssh/id_rsa

Are you running Windows? Unfortunately, you're going to have an issue with that last one. To work around this Windows permissions issue you will need copy your SSH key into the container by executing the following commands within the container bash shell:

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 environment make sure that:

  1. 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 DATABASE `elentra_cbe` 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';
    GRANT ALL ON elentra_cbe.* TO 'elentra'@'localhost';
  2. 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.

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

Install the NPM dependencies

Run the following in the elentra-1x-me directory, to compile the vite bundle (again in the docker shell):

npm install
npm run build

Proceed to Browser

Deploying Elentra

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.

Prerequisites

  • Elentra Developer Docker Environment

Deployment

# 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

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

Please where you will be asked for your full name, the institution you belong to, your e-mail address, and your GitHub.com username. Once your contributor request has been approved you will receive an invite from GitHub.com to join the organization.

Make sure that you have completely installed the 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 that has already been adopted by Google Chrome.

Next, you must add your SSH public key to your GitHub profile in the section. Using either Terminal or Git Bash on your host desktop, run:

Please make sure your SSH Public Key (~/.ssh/id_rsa.pub) has been added to GitHub's section before proceeding.

Your development environment meets the

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 - . This service mirrors our dependencies from their original location and provides a reliable, redundant, and consistent dependency source for our deployment processes.

Elentra 1.26 introduces a bundle containing JavaScript dependencies such as jQuery and Bootstrap, which uses NPM to ensure that these libraries stay up-to-date.

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:

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.

https://elentra.slack.com
https://elentra.atlassian.net
developer-l@elentra.org
community-l@elentra.org
https://github.com
Your Profile > Settings
two-factor authentication enabled for your GitHub account
Elentra Contributor Agreement
sign the Elentra Contributor Agreement in Adobe Sign
ElentraProject
not-yet-approved RFC standard
SSH and GPG keys
SSH and GPG keys
System Requirements
https://packagist.com
vite
http://elentra-1x-me.localhost
Deployer
Highly Recommended Software Stack
Docker Desktop
Git
SourceTree
GitKracken
Sequel Ace
DBeaver
Visual Studio Code
Postman
Node.js
Meld Merge
Araxis Merge
DbSchema