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.

Click the "Fork" button at the top of the page

When creating a new institutional fork, ensure that you are creating under the appropriate GitHub organization.

Forking ElentraProject/elentra-1x-api into the "xyz" 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.

Click the trash icon on each branch to delete

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.

SSH is recommended when working with git remotes

In this example we are using Atlassian's Source Tree which can be downloaded here.

Creating the Branded API

Configuring the Project Server

In this example are using GitLab. However, these instructions should be similar for other popular services such as GitHub or BitBucket.

We already have a branded edition of Elentra ME so we can begin by creating a new project under the same group.

Click the "New Project" button to create a new repository

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.

(Optional) Add a third remote called consortium that points to the ElentraProject API so that you can keep in sync with the latest updates to your Elentra release branch.

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.

In this example we are setting up deployments for the staging server; however, the steps for production are exactly the same.

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-keygen

Do 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.pub

Only 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 [e-mail]

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.
[e-mail]: 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.

If you are unsure which version of the Elentra API your installation is targeting, search for"elentrapackages/elentra-1x-api"in your Elentra ME composer.json file. You can also review the Compatibility Matrix documentation to find the appropriate version.

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.

Check the "Push tag" option to ensure that releases are published to your branded repository.

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": "[e-mail]:elentra-xyz/elentra-1x-api.git"
        },
        {"type": "composer", "url": "https://repo.packagist.com/elentra/"},
        {"packagist.org": false}
    ],

Deploying Updates

Via Deployer

Changes to a Branded Edition Elentra API can be deployed automatically with Deployer instead of updating and committing the composer.lock file before each deployment.

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);

Via composer.lock

The composer.lock is a file that keeps track of exactly which versions of a project's dependencies were used when it was generated. This speeds up the dependency resolution process during deployment and ensures a consistent state each time composer install is run. What this means for us is that because the Elentra API is currently included as a composer dependency, we must regenerate this file each time we tag a new release of the Elentra API.

The composer.lock file must be regenerated each time you deploy new changes to the Branded Edition Elentra API.

To regenerate the lock file, run composer update for only the API package

[root@97b013f7a4a7 elentra-1x-me]# composer update elentrapackages/elentra-1x-api

The first time you update the composer lock on your local development environment, you may be asked to confirm that you trust the project git server.

Loading composer repositories with package information
The authenticity of host 'gitlab.com (35.231.145.151)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
ECDSA key fingerprint is MD5:f1:d0:fb:46:73:7a:70:92:5a:ab:5d:ef:43:e2:1c:35.
Are you sure you want to continue connecting (yes/no)? yes
Updating dependencies (including require-dev)

After the dependencies are updated, commit both the composer.json and composer.lock file and push the commits to your Branded Edition Elentra repository remote.

You will only need to commit the composer.lock file when tagging releases in the future.

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 staging

Keeping 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.

Release branches are only created after a breaking change has been introduced. If there is not a release branch for the current version of the Elentra API, then the HEAD of the consortium master will point to the most recent tag.

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 permissions

This 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_rsa