Branded API Setup
Creating an Institutional Fork
Forking the API
Begin by creating a new fork from the ElentraProject/elentra-1x-api repository. This will serve as your organization's Institutional Fork of Elentra API. Just like Elentra ME, this is where new features or bug fixes will be developed that are to be contributed back to the Consortium.
When creating a new institutional fork, ensure that you are creating under the appropriate GitHub organization.
After we have succesfully created our institutional fork of the API, we can then clean up the repository be pruning all of the branches.
Git repositories must have at least one branch, leave the default branch undeleted.
Cloning the Repository
Now we must clone our new institutional fork repository on our local development machine so that we can begin configuring our branded edition of the API.
Creating the Branded API
Configuring the Project Server
We already have a branded edition of Elentra ME so we can begin by creating a new project under the same group.
Make sure the repository is easily distinguishable by adding a description to indicate that this repository is the branded edition of the API.
After confirming the project details, a new item should now appear in the list next to your branded Elentra ME project.
Configuring Git Remotes
Click into the repository and copy the SSH clone URL.
Configure the remotes of the repository cloned in the previous section by navigating to Repository > Repository Settings in the SourceTree menu.
Modify the git remotes so that origin points to your new branded edition and upstream points to your institutional fork.
Fetch all remotes and then check out the consortium master branch. We recommend that you base your branded edition off of master rather than develop because it is the most stable and up to date release tags.
Initializing the Branded Repository
After checking out the consortium master branch, push this branch to the origin remote which will serve as the main branch for the branded API.
Because the API is included as a composer package by Elentra, branded APIs cannot support multiple environments such as staging or production. Instead choose a single branch to serve as the stable base which will serve as the main release branch for deployments.
Check to make that your branded API master branch and the ElentraProject master branch are in an identical state.
Deploying the Branded Edition Elentra API
Generating Deployment Keys
In order to deploy our new branded API we must generate a new SSH key so that our private repository can be read from the application server.
Begin by using the ssh-keygen command to initialize a new SSH key and press the enter key through each question.
staging@xyz-app-01:~$ ssh-keygenDo not enter a passphrase during the key generation process.
Generating public/private rsa key pair.
Enter file in which to save the key (/home/staging/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/staging/.ssh/id_rsa.
Your public key has been saved in /home/staging/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:lEDmSOmr78wr+AKEjWtkfRbTpCHC5Sdw+aQ+7TxsbkE staging@xyz-app-01
The key's randomart image is:
+---[RSA 2048]----+
|.o.+o+*. |
| .=ooBoo . |
|.o.+=o+ o |
|o+.o+E . |
|+.. =. S |
|o. o.o |
|o. .= . |
|o oo B |
| o.+Xo. |
+----[SHA256]-----+After you have successfully generated a new SSH key for the staging user, copy the newly generated public key and add it to the list of deployment keys for your Branded Edition Elentra API repository.
staging@xyz-app-01:~$ cat ~/.ssh/id_rsa.pubOnly read access is required to deploy Elentra. Allowing write access to the repository is considered a security risk, so please ensure that only read access is granted.
A new item for the staging user should appear in the list of configured deployment keys. You can now go ahead and repeat the above to configure deployments for the production user.
Enabling SSH Cloning
From our application server simply attempt to connect to our git project server over SSH. You will be prompted to add the server to the lists of known hosts. Type 'yes' and press the enter key.
staging@xyz-app-01:~$ ssh [email protected]The authenticity of host 'gitlab.com (35.231.145.151)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'gitlab.com,35.231.145.151' (ECDSA) to the list of known hosts.
[email protected]: Permission denied (publickey).Tagging Releases
Depending on what version of Elentra you are running at your organization, the changes that you make to the Elentra API may be tagged by a version that differs from the most recent version in the ElentraProject repository. At the time of writing, the most recent release of the Elentra API is v4.1.3.
Elentra API follows semantic versioning, at the time of writing we are targeting any minor release that is greater than v4.1. This could include releases such as v4.0.2, v4.1.3 and so on.
"elentrapackages/elentra-1x-api": "~4.0"Changes made to the Elentra API will usually be based on the most recent minor version of whichever release your Elentra installation is targeting. To keep up to date with the latest fixes and improvements to the API we recommend versioning releases in a way that does not conflict with our use of semantic versioning. Here we have chosen to tag each new release of the API as a subversion–represented by the current date in year, month, day format–to the most recent minor release.
After creating the tag you should see an new item appear in the list of tags for your branded repository.
Configuring Composer
Add a new entry to the repositories section in the composer.json file in your Elentra installation above the packagist entry. The repository type should be set to "git" and the "url" set to the SSH URL from your branded repository.
"repositories": [
{
"name": "elentrapackages/elentra-1x-api",
"type": "git",
"url": "[email protected]:elentra-xyz/elentra-1x-api.git"
},
{"type": "composer", "url": "https://repo.packagist.com/elentra/"},
{"packagist.org": false}
],Deploying Updates
In order to have Elentra API updates automatically deployed during each deployment, change the enable_branded_api setting in your deployment/deploy.php file to true.
// Elentra API (obtained via Composer by default). Default value is false.
set('enable_branded_api', true);
The Branded Edition Elentra API will be used by default when deploying Elentra. Changes can be deployed simply by running the same Deployer commands for the environment you wish to deploy to.
[root@97b013f7a4a7 deployment]# dep deploy stagingKeeping Up to Date
Improvements are continuously being added to the Elentra API, so it is important to ensure that your Branded Edition Elentra API remains up to date. In addition to receiving the latest bug fixes and security patches, merge conflicts can be reduced by periodically merging commits from the consortium master branch.
We advise against merging commits from the consortium develop branch because it may have breaking changes introduced during the development cycle.
Troubleshooting
Unprotected Private Key Error on Windows
When attempting to deploy from a Windows machine for the first time or if you have recently restarted the Elentra Developer Docker environment, you may receive the following error:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: UNPROTECTED PRIVATE KEY FILE! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Permissions 0644 for '/root/.ssh/id_rsa' are too open.
It is required that your private key files are NOT accessible by others.
This private key will be ignored.
Load key "/root/.ssh/id_rsa": bad permissionsThis is happens because by default, your SSH key is mounted within the Docker container using secrets and Docker is unable to properly translate Windows ACLs to standard UNIX file system permissions. In order to correct this issue we must remove the link created by Docker and manually copy the SSH key into the container.
[root@a66ddbd8a408 /]# rm /root/.ssh/id_rsa
[root@a66ddbd8a408 /]# cp /run/secrets/ssh_private_key /root/.ssh/id_rsa
[root@a66ddbd8a408 /]# chmod 0400 /root/.ssh/id_rsaLast updated