Application Configuration using Environment Variables in .NET and Java

Official Content
This documentation is valid for:

In various scenarios, it is common practice to read configuration information from environment variables, rather than configuration files.  This document details how to achieve this in the .NET and Java generators. 

Each configuration entry of an application can be read from an environment variable. This environment variable must be prefixed with 'GX_' and it must be all in capital letters.

.NET

For the case of .NET, the variable must be called the same as it is defined in the web.config.

Suppose you have a Docker Image (named "environmenttest.netenvironment") with a web app that points to a production DB. Now you want to raise an instance of that image pointing to the Test DB (named "EnvTest"). For that you execute the following command:

docker run --rm -e GX_CONNECTION-DEFAULT-DB=EnvTest environmenttest.netenvironment

where the flag -e sets the environment variable GX_Connection-Default-DB (same name as it has in the web.config) to "EnvTest". When the application starts and wants to read the value of that property, it first checks if there is an environment variable with that name. As it exists, it takes that value.

If on the contrary, you want to raise the same image (environmenttest.netenvironment) against the production DB (EnvProd), execute the following command:

docker run --rm -e GX_CONNECTION-DEFAULT-DB=EnvProd environmenttest.netenvironment

The same works for any configuration property of the web.config. Whenever you are going to look for a configuration property, the application first searches for an environment variable with that name.

Name Environment Variable (NET) Environment Variable (JAVA)
Database Name GX_CONNECTION-DEFAULT-DB Does not apply. Use GX_DEFAULT_DB_URL instead
Connection endpoint

GX_CONNECTION-DEFAULT-DATASOURCE

GX_DEFAULT_DB_URL

Sample: 

  • jdbc:mysql://hostname:3306/mybdname?useSSL=false
Connection username GX_CONNECTION-DEFAULT-USER GX_DEFAULT_USER_ID
Connection password GX_CONNECTION-DEFAULT-PASSWORD GX_DEFAULT_USER_PASSWORD
Connection port GX_CONNECTION-DEFAULT-PORT Does not apply. Use GX_DEFAULT_DB_URL instead

 

Environment Variables Database configuration Example (.NET)

GX_CONNECTION-DEFAULT-DB=test
GX_CONNECTION-DEFAULT-DATASOURCE=mysql8
GX_CONNECTION-DEFAULT-USER=root
GX_CONNECTION-DEFAULT-PASSWORD=admin
GX_CONNECTION-DEFAULT-PORT=3307

Environment Variables Database configuration Example (JAVA)

GX_DEFAULT_DB_USER_ID=root
GX_DEFAULT_DB_PASSWORD=admin
GX_DEFAULT_DB_URL=jdbc:mysql://hostname:3306/mybdname?useSSL=false

 

.NET Core

.NET Core works just like .NET, but the settings are stored in a file called appsettings.json

Java

The case of Java is a bit different because Java has the client.cfg that works differently, it has sections.

For example, suppose you have a section called com.environmenttest|DEFAULT (which is the default DBMS of your environment) where there is a DB_URL entry that has the following url to the DBMS 

jdbc:jtds:sqlserver://172.16.3.21:1435/EnvProd

If you want to change that value, you have to create an environment variable concatenating the section and the property, all in upper case, replacing points and pipes with an underscore. For example, if you create the variable GX_COM_ENVIRONMENTTEST_DEFAULT_DB_URL you overwrite the value of the client.cfg. The value of that variable becomes the one that the app handles.

You can also create the variable without specifying the namespace, like this: GX_DEFAULT_DB_URL.

In this case, to launch the container with this variable, you have to execute the following command to connect to the test DB:

docker run --rm -p 8890: 8080 -e GX_DEFAULT_DB_URL=jdbc:jtds:sqlserver://172.16.3.21:1435/EnvTest environmenttestjavaenvironment

and the following one for the production DB:

docker run --rm -p 8890: 8080 -e GX_DEFAULT_DB_URL=jdbc:jtds:sqlserver://172.16.3.21:1435/EnvProd environmenttestjavaenvironment

When searching for the DB_URL environment variable in the default data store, the following environment variable will be searched for:

GX_COM_ENVIRONMENTTEST_DEFAULT_DB_URL 

If no value is found for that entry, then GX_DEFAULT_DB_URL will be searched for. 

AWS MYSQL Sample

docker run --rm -p 8890: 8080 -e GX_DEFAULT_DB_URL=jdbc:mysql://myrdsname.us-east-1.rds.amazonaws.com/mybdname?useSSL=false

Availability

This feature is available as of GeneXus 15 upgrade 12

See also

Application Configuration using Environment Variables
Application Configuration using Environment Variables in Cloud Services
How to Deploy an Application to Docker