Skip to main content

SciForge API: Development Configuration

Video: Environment Configuration Example

 

The configuration that is managed by the .env (environment) file, and a DNS address for the SciForge development environment, are the final aspects of setup that need to be completed in order for the development environment to successfully be started.

Environment file

The environment file has three primary purposes.

  • To have a securable file in the back-end that hides sensitive information from the repository and from API interactions over the web.
  • To have a place to configure different environments. This file is specifically ignored by gitignore, such that whatever configuration exists in any particular development environment will not be sent back to the repository.
  • To mimic the way that the production environment is configured and started.

The purpose of the current .env values that are utilized by SciForge are explained below. Since the .env file is ignored, additional values may be added and utilized in plugins, as needed. If so, the promotion of changes to the test and production environments may require specific instructions to be provided. Promotion is largely automated, which will be discussed in a later section. The setting of environment variables requires manual input.

The readme in the SciForge COTS repository is generally kept up to date with respect to the changes to .env variables and their purposes.

Steps

  • Use your regular linux user account
  • In the /src directory of the SciForge project, copy the .env.example to .env
  • Edit the variables in the new .env file, based on the below information

For example:

cd ./elab-api
cp .env.example .env
nano .env #or use VS Code, vi, or other preference

URL / Domain

  • CLIENT_CODE - This should match the subdomain you want to use with a DNS in the sciforge.net domain. For example, if the URL you will access the dev playground at is https://example-api.sciforge.net, then this value would be set to example-api.

Database Access

  • ELAB_SQL_UID=User name of DB user authorized to read/write to Elab DB
  • ELAB_SQL_PWD=Password
  • ELAB_SQL_SVR=Server name or IP address hosting Elab DB
  • ELAB_SQL_DB=Database

ELAB Settings. These are needed for some file handling and report engine calls.

  • API_ELAB_SITE - The elab site url. For example, https://example.lablynx.com/elab
  • API_WSDL_TOKEN - Get a token from LabLynx
  • API_ELAB_FOLDER - The folder that the IIS Elab site is pointed to. For example C:\Sites\Example
  • API_ELAB_VIRT_PATH - the folder that the main elab instance is in, relative to API_ELAB_FOLDER. For example, \elab

Various tokens.

Values can be anything, but should be secure, especially for JWT.

  • API_REDIS_SECRET - token to secure communications with dockerized redis, included in docker stack.
  • API_JWT_ACCESS_TOKEN_SECRET - token to secure JWT communications, used in API authorization.
  • API_JWT_REFRESH_TOKEN_SECRET - token to secure JWT communications, used when refreshing JWT.

Settings when authorization with opensocial/SCIM is required

  • OPENSOCIALAUTH_ENABLED - true or false
  • OPENSOCIALURL - the opensocial URL
  • SCIFORGE_AUTHORIZATION_ENABLED - true or false

Misc

  • APPLICATIONNAME - Currently, always ElabPortal

These are not yet used, reserved for future plans

  • API_PG_UID
  • API_PG_PWD
  • API_PG_SVR
  • API_PG_DB
  • API_AWS_AccesskeyID
  • API_AWS_Secretaccesskey

Example:

For this example, the address https://training.sciforge.net/graphql will open the GraphQL web sandbox for the dev environment, once started, and Elab data will come from the training_dev database on server 192.168.1.154, as used by the development Elab site, https://dev-jd.lablynx.com/training/elab.

CLIENT_CODE=training
ELAB_SQL_UID=sa
ELAB_SQL_PWD=supersecuredatabasepassword
ELAB_SQL_SVR=192.168.1.154
ELAB_SQL_DB=training_dev
API_ELAB_SITE=https://dev-jd.lablynx.com/training/elab
API_WSDL_TOKEN=xxxxxxxxxxxxxxxxxxxxxx
API_ELAB_FOLDER=C:\Sites\Training
API_ELAB_VIRT_PATH=\elab
API_REDIS_SECRET=ihaveasecret
API_JWT_ACCESS_TOKEN_SECRET=ihaveasecret
API_JWT_REFRESH_TOKEN_SECRET=ihaveasecret
API_AWS_AccesskeyID=ihaveasecret
API_AWS_Secretaccesskey=ihaveasecret
APPLICATIONNAME=ElabPortal
OPENSOCIALAUTH_ENABLED=false
OPENSOCIALURL=x
SCIFORGE_AUTHORIZATION_ENABLED=false
API_PG_UID=xx
API_PG_PWD=xx
API_PG_SVR=xx
API_PG_DB=xx

DNS

Video: SciForce API: Development DNS

In the dockerized development environment that is reverse proxied via Traefik, the GraphQL API and sandbox are not accessible via http, local or remote. Since https is required, a DNS address entry is therefore also required, that publicly identifies the development machine. This maintains the best practice that the development environment be identical to production.

Above, the CLIENTCODE setting is noted as being used to determine an address in the sciforge.net domain. As noted in the Prerequisite module, this is a domain that is owned by LabLynx. LabLynx will create a DNS A or CNAME record as needed to support this, on request.

Note that the development machine has two public DNS entries, in total. One for Traefik, and one for SciForge.

Where development is not done by LabLynx personnel, and the development environment is therefore not in the LabLynx environment, some companies may have concerns about the use of the sciforge domain and want to use domains that they own and manage. If this is the case:

  • Traefik configuration may need to be edited, as it is configured to get certificates via Let’s Encrypt. This editing is outside of the scope of this training module.
  • SciForge COTS repository contains the file “docker-compose.yml” in the root directory. This will need to be edited
    • It is this line that causes the sciforge.net domain to be used. Edit this to the desired domain.
      • traefik.frontend.rule: Host:${SITE}.sciforge.net
    • This is a file in the SciForge COTS repository, which will affect pushing and pulling with git, when edited
      • Access to this repository is read-only. Pushes will fail.
      • You will often want to make sure that you have the latest code, and so git pull is expected to be a frequently used command.
      • After the file is changed, git will not pull until changes are committed or reverted. Assuming the file is reverted, you will need to remember to re-edit this file after the git pull.
Back to top