Gravitee Environment Variable Configuration for Docker

I have recently been a part of a project to set up and configure Gravitee (https://gravitee.io/) to front a customer’s API for public use.  As a team, we have really been enjoying the toolset that Gravitee provides for API management.  For those who don’t know about Gravitee, here’s what it is  according to their own definition:

Gravitee.io is a flexible, lightweight and blazing-fast open source API Platform that helps your organization control finely who, when and how users access your APIs.

Recently, we did have to work a bit harder with configuration specific to the Docker environment variables.  Gravitee’s configuration is typically done via the gravitee.yml file.  Alternatively, you can also configure via system properties or environment variables.  In our case, using Docker via the install guide, we needed to do configuration via environment variables through our docker-compose.yml.  Following some basic rules, you can translate any of the gravitee.yml default configurations with Docker environment variables.  Here are some examples of what we learned along the way.

Rules

According to Gravitee’s configuration documentation:

You can override the default configuration (gravitee.yml) and system properties by defining environment variables.

For example, if you want to override this property in the gravitee.yml file:

management:
    Mongodb:
        dbname: myDatabase

You have to define one of the following variables in your Docker environment variables:

GRAVITEE_MANAGEMENT_MONGODB_DBNAME=myDatabase
GRAVITEE.MANAGEMENT.MONGODB.DBNAME=myDatabase
gravitee_management_mongodb_dbname=myDatabase
gravitee.management.mongodb.dbname=myDatabase

Notice the prefixed gravitee on each example and the variations of uppercase, lowercase, underscores, and dot formats.  Apart from that, it is a simple translation of the structure from the gravitee.yml file to the underscored or dot formed versions.

Although allowed by Gravitee, casing and hyphenation can be a problem in some systems. Because of this, Gravitee recommends to write variable names as lowercase and remove any hyphens.

Email

After the setup of an account in Gravitee, the system sends a verification email to the email specified when creating the account.  This requires a properly configured outgoing mail server.  The email references in the gravitee.yml file are as follows.

# SMTP configuration used to send mails
email:
	enabled: false
	host: smtp.my.domain
	subject: "[Gravitee.io] %s"
	port: 587
	from: noreply@my.domain
	username: user@my.domain
	password: password
	# properties:
		# auth: true
		# starttls.enable: true
		# ssl.trust: smtp.gmail.com

The corresponding values for in Docker environment variables are as follows (using the underscored form):

gravitee_email_enabled=true
gravitee_email_host=smtp.my.domain
gravitee_email_port=25
gravitee_email_from=api@my.domain
gravitee_email_username=user@my.domain
gravitee_email_password=password

Portal URL

So, after the emails were being delivered we recognized that the URLs offered within the email were prefixed with http://localhost:3000.  We created an override for the portal URL referenced in the gravitee.yml as:

# The portal URL used in emails
portalURL: http://localhost:3000/

The environment variable counterpart looks like the following (using the dot form):

gravitee.portalURL=https://api.my.domain/

Password

As another requirement, we needed to change the default password set up by Gravitee and create our own password for use with the portal.  The settings for authentication look like the following in the gravitee.yml file:

# Authentication and identity sources
security:
	providers:
		- type: memory
			users:
				- user:
					username: user
					#firstname:
					#lastname:
					password: $2a$10$9kjw/SH9gucCId3Lnt6EmuFreUAcXSZgpvAYuW2ISv7hSOhHRH1AO
					roles: MANAGEMENT:USER, PORTAL:USER
					# Useful to receive notifications
					#email:
				- user:
					username: admin
					#firstname:
					#lastname:
					password: $2a$10$Ihk05VSds5rUSgMdsMVi9OKMIx2yUvMz7y9VP3rJmQeizZLrhLMyq
					roles: MANAGEMENT:ADMIN, PORTAL:ADMIN
					#email:

So, first, we have to learn how Gravitee allows us to overwrite array values. Writing these environment variables in the aforementioned underscore or dot forms you can use:

gravitee_security_providers_0_users_1=newpassword

or

gravitee.security.providers[0].users[1].password=password

With these variable references above we are targeting the admin user password.  The arrays and their indexes are part of the variable name like users_1 or users[1].  The users_1 and users[1 are equivalent here and represent the element in the first index of the user’s array.  Gravitee allows for both types of reference.

As an additional requirement for password values you will also need to provide your new password as a hashed bcrypt value (supports only $2a$ algorithm).

Summary

With the proper interpretation of Gravitee’s gravitee.yml configuration file and the translation of the settings into either an underscore or dot formed version you can override any of the values present in the configuration file and make your Gravitee installation perform as you desire.

We really like what Gravitee provides for features and especially its ease of set up on Docker.  If you need any help with your Gravitee setup or would like help in fronting your API with Gravitee we have a team to assist you with your APIM needs.