Server configuration

Most of the configuration options are directly managed in the web interface. Here we list the configuration options that can only be configured on the level of the Docker container.

note

After updating the Docker compose file and applying it with docker compose up, the server will be restarted if configuration changes are detected.

Using a configuration file

GGCE Server configuration options can also be loaded from a custom.properties file. Please note the different notation of property keys: these are case sensitive and use . (dots) instead of - (dashes): accession.format2 instead of ACCESSION_FORMAT2.

The full path to the custom.properties file needs to be provided to docker as an environment variable:

  environment:
    - CONFIG_FILE=/path/to/custom.properties

tip

We recommend declaring the settings using environment in the compose file.

Accession number format

Accession numbers in different genebanks use various formats, but they all usually contain a part that is numerical and incremented as material is added to the collection. Some examples of accession numbers are: IRGC 32013, PI 123123, TMp-419 and VI0000134a.

GGCE uses Accession Prefix, Sequence Number and Accession Suffix. The Sequence number is numerical, while the other two are text fields. These three fields are merged to create the formatted accession number. The default format uses a single space character as a separator.

The formatting can be configured with server environment variables ACCESSION_FORMAT1, ACCESSION_FORMAT2 AND ACCESSION_FORMAT3.

Format	ACCESSION_FORMAT1	ACCESSION_FORMAT2	ACCESSION_FORMAT3
default	{0}	\ {0,number,####}	\ {0}
IRGC 32013	default	default	default
IRGC 32013 abc	default	default	default
IRGC 32013 abc9x	default	default	default
IRGC 32013abc	default	default	{0}
IRGC 32013-abc	default	default	-{0}
TMp-419	default	-{0,number,####}	default
TMp-419.abc	default	-{0,number,####}	.{0}
VI000012	default	{0,number,000000}	default
VI000012 abc	default	{0,number,000000}	default
VI000012abc	default	{0,number,000000}	{0}
KEN 000033 abc	default	\ {0,number,000000}	default
KEN 000033-abc	default	\ {0,number,000000}	-{0}

tip

Zero-padding is rarely used and should generally be avoided. If you need to use zero-padding, then the number of zeros in the last part of the format string controls how many zeros wiil be used (e.g. {0,number,0000000000} will use ten zeros).

ggce.yml

services:
  ggce-api:
    image: dockerhub.croptrust.org/grin-global/grin-global-server:...
    ...
    environment:
      # Accession format: VI000012a
      - ACCESSION_FORMAT2={0,number,000000}
      - ACCESSION_FORMAT3={0}

custom.properties

# Accession format: VI000012a
accession.format2={0,number,000000}
accession.format3={0}

Inventory number format

Formatting of the inventory number follows the same logic as that of accession number, only that it uses Inventory Prefix, Sequence Number, Inventory Suffix and Germplasm form.

The formatting can be configured with server environment variables INVENTORY_FORMAT1, INVENTORY_FORMAT2, INVENTORY_FORMAT3 and INVENTORY_FORMAT4.

Format	INVENTORY_FORMAT1	INVENTORY_FORMAT2	INVENTORY_FORMAT3	INVENTORY_FORMAT4
default	{0}	\ {0,number,####}	\ {0}	\ {0}
INV 1234 abc SD	default	default	default	default
INV-1234 abc SD	default	-{0,number,####}	default	default
INV1234 abc SD	default	{0,number,####}	default	default
INV00001234abc.SD	default	{0,number,00000000}	{0}	.{0}

tip

Note that the inventory number and its formatting have no effect on the barcode of the inventory.

ggce.yml

environment:
  # Inventory format: INV00001234a.SD
  - INVENTORY_FORMAT2={0,number,00000000}
  - INVENTORY_FORMAT3={0}
  - INVENTORY_FORMAT4=.{0}

custom.properties

# Inventory format: INV00001234a.SD
inventory.format2={0,number,00000000}
inventory.format3={0}
inventory.format4=.{0}

GLIS DOI and Easy-SMTA

Minting DOIs using the DOI Registration Service of the Global Information System (GLIS) of ITPGRFA and automated reporting on SMTA distributions from GGCE to Easy-SMTA requires proper configuration of the service endpoints in ggce.yml file.

No trailing slashes!

Make sure you use the settings exactly as listed below. Including a trailing / will result in errors!

ITPGRFA GLIS

• Test environment: https://glis.qa.fao.org (note the .qa) Default
• Production environment: https://glis.fao.org

ITPGRFA Easy-SMTA

• Test environment: https://easy-smta-test.planttreaty.org Default
• Production environment: https://mls.planttreaty.org

The login credentials for both Easy-SMTA and DOI service are configurable in AppSettings (to be documented).

ggce.yml

environment:
  # ITPGRFA GLIS service
  - ITPGRFA_GLIS_BASEPATH=https://glis.qa.fao.org
  # ITPGRFA Easy-SMTA service
  - ITPGRFA_EASYSMTA_BASEPATH=https://easy-smta-test.planttreaty.org

custom.properties

# ITPGRFA GLIS service
itpgrfa.glis.basepath=https://glis.qa.fao.org
# ITPGRFA Easy-SMTA
itpgrfa.easysmta.basepath=https://easy-smta-test.planttreaty.org

OAuth

On first startup, the server ensures that there is at least one OAuth client available. The clientId and secret of this default client can be configured using DEFAULT_OAUTHCLIENT_CLIENTID and DEFAULT_OAUTHCLIENT_CLIENTSECRET.

OAUTH_CLIENTID_SUFFIX is used when generating new OAuth clients. Client IDs are created using the format:
<auto-generated>@<OAUTH_CLIENTID_SUFFIX>.

ggce.yml

environment:
  # OAuth
  - OAUTH_CLIENTID_SUFFIX=localhost
  - DEFAULT_OAUTHCLIENT_CLIENTID=defaultclient@localhost
  - DEFAULT_OAUTHCLIENT_CLIENTSECRET=changeme

custom.properties

# OAuth
oauth.clientId.suffix=localhost
default.oauthclient.clientId=defaultclient@localhost
default.oauthclient.clientSecret=changeme

SMTP

Sending email notifications requires accesss to your SMTP server.

Setting	Default	Description
MAIL_USER_FROM	test@localhost	The email address that appears as the sender of emails from GGCE
MAIL_HOST	none	SMTP server name or IP address
MAIL_PORT	25	SMTP port. Ports 465 (SSL) and 587 (TLS) are common.
MAIL_SMTP_AUTH	true	Does your SMTP server require authentication? If so, then you must set the username and password!
MAIL_USER_NAME		SMTP username
MAIL_USER_PASSWORD		SMTP password
MAIL_SMTP_SSL_ENABLE	true	Expect SSL connection (usually on port 465)
MAIL_SMTP_STARTTLS_ENABLE	true	Enable TLS (usually on port 587)
MAIL_ASYNC	true	Use a separate worker thread when connecting the SMTP server
MAIL_DEBUG	false	Write contents of email messages to the log file

ggce.yml

environment:
  # SMTP
  - MAIL_USER_FROM=My Genebank <xxxx@gmail.com>
  - MAIL_USER_NAME=xxxx@gmail.com
  - MAIL_USER_PASSWORD=....
  - MAIL_HOST=smtp.gmail.com
  - MAIL_PORT=587
  - MAIL_SMTP_SSL_ENABLE=true
  - MAIL_SMTP_STARTTLS_ENABLE=true
  - MAIL_ASYNC=true
  - MAIL_DEBUG=false
  - MAIL_SMTP_AUTH=TRUE

custom.properties

# SMTP
mail.host=
mail.port=25
mail.async=true
mail.debug=false
mail.user.from=test@localhost
mail.user.password=
mail.user.name=
mail.smtp.ssl.enable=true
mail.smtp.starttls.enable=true
mail.smtp.auth=true

Audit logs

GGCE keeps record of all changes made to the data and stores who, when and what changed. The retention period controls how long these logs are kept in the database and older logs are regularly removed from the database.

Period	AUDITLOG_RETENTIONPERIOD
Three months	3M (default)
30 days	30D
Six months	6M
One year	1Y
One year and two months	1Y2M

ggce.yml

environment:
  # Auditlog retention period
  - AUDITLOG_RETENTIONPERIOD=3M

custom.properties

# Auditlog retention period
auditlog.retentionPeriod=3M

API response page size

API requests may result in thousands of resulting records, therefore the response from the API is always paginated. The larger the page size, the fewer API calls need to be made to retrieve all records, but this first requires more processing on the server, more data to transfer to the client, and parsing of larger batches of data on the client. Smaller page sizes are quicker to process, but require more API calls.

Interactive client applications should use smaller page size to quickly retrieve and present results to the user. Larger sizes are useful for background tasks and other non-interactive cases.

Setting	Default	Description
API_PAGE_DEFAULT	100	The number of elements returned per page when not explicitly specified in the request
API_PAGE_MAX	1000	The maximum allowed number of elements per page (even if larger page size is requested)

ggce.yml

environment:
  # API pagination
  - API_PAGE_DEFAULT=100
  - API_PAGE_MAX=1000

custom.properties

# API pagination
api.page.default=100
api.page.max=1000

Maximum rows returned for CT

The Curator Tool uses a very specific pagination system.

If your use of CT requires more than the default 100,000 rows you need to adjust DATAVIEW_MAX_ROWS setting:

Setting	Default	Description
DATAVIEW_MAX_ROWS	100000	The maximum number of rows that can be requested in a single SOAP getData call

ggce.yml

environment:
  # SOAP max rows allowed
  - DATAVIEW_MAX_ROWS=100000

custom.properties

# SOAP max rows allowed
dataview.max.rows=100000

All configuration options

GGCE accepts a number of system configuration options. The full list and their default values are listed in application.properties.

For example, the default database connection parameters are:

db.url=jdbc:sqlserver://localhost:1433;DatabaseName=gringlobal
db.username=sa
db.password=sa1

Any of the properties can be configured using environment variables. Please convert the property name to uppercase and replace . (dots) with _ (underscores): db.url becomes DB_URL.