Configuration Files

testgrinder service will be discontinued on January 31, 2025

testgrinder SMPC was discontinued as of February 1, 2024

Each tg-app server expects a set of configuration files in its /home/testgrinder/tg-app/config/provision directory. These files can either be created manually or by providing specially formatted User Data as part of the tg-app launch. If such files do not exist, testgrinder will create them with workable defaults that are sufficient for launching, but not enough for testgrinder to operate fully. You will have to edit/replace these files to complete the deployment.

If your testgrinder deployment will have multiple tg-app servers (e.g. for increased fault tolerance or higher capacity), make sure all tg-app servers use the same set of configuration files. The best way to achieve that is to encode the configuration files in User Data format and supply the result as User Data during the tg-app launch.

File	Description
.env	A set of configuration settings and their values
ssl_cert.crt	SSL certificate for the testgrinder site
ssl_private_key.key	SSL certificate private key

.env

If testgrinder doesn't find the .env file, it will create one with suitable defaults. You may then edit the file, or choose to provide your own via the User Data mechanism described later.

The file consists of entries formatted as <SETTING>: <VALUE>, for example:

STAGE_NAME: eval
AWS_REGION: us-east-1

Settings that tg-app will recognize in .env:

Setting	Default value	Description
STAGE_NAME	eval	unique testgrinder instance identifier; useful if you have several deployments; will appear in tg-bot names, and bugsnag reports
AWS_REGION	region testgrinder was launched in	AWS region in which testgrinder operates
FORCE_SSL	true	If true, force http requests to redirect to https
HOSTNAME	tg-eval-app-%i	hostname for tg-app server to set; %i in it will be replaced with tg-app AWS instance id
DOMAIN_WEB	tg-app instance public hostname	domain that users will use to access testgrinder (and for which the SSL certificate is issued)
DEVISE_SECRET_KEY	random 128 character string	used to generate tokens embedded in account management emails; recommended lengths - 128 characters
DEVISE_PEPPER	random 128 character string	added to user passwords prior to hashing; recommended lengths - 128 characters
SECRET_KEY_BASE	random 128 character string	used to encrypt cookies; recommended lengths - 128 characters
DBDATA_SECRET_KEY	random 32 character string	used to encrypt sensitive values in the database; must be 32 characters long
MONGODB_URI	mongodb://127.0.0.1:27017/tg_app_production	URI of the testgrinder database; default value points to the locally installed MongoDB database
DISABLE_LOCAL_MONGODB	not provided	Set to true to disable the locally installed MongoDB.
SMTP_HOST	not provided	SMTP server hostname
SMTP_PORT	not provided	SMTP server port
SMTP_USERNAME	not provided	username to use when connecting to the SMTP server
SMTP_PASSWORD	not provided	password to use when connecting to the SMTP server
MONIT_NOTIFY_EMAIL	not provided	Email to which Monit should send notifications
MONIT_NOTIFY_FROM_EMAIL	not provided	Email address that will appear in the "From" field of Monit notification emails
TIMEZONE	America/New_York	Timezone for tg-app to set; get the list of available timezones with timedatectl list-timezones
PAPERTRAIL	not provided	Set to enable papertrail.com integration
BUGSNAG_API_KEY	not provided	Set to enable bugsnag.com integration

Here's an example of a .env generated by tg-app if it doesn't find one on launch:

Do not use key values listed below, generate your own

# unique testgrinder instance identifier; useful if you have several deployments; will appear in bugsnag issue reports
STAGE_NAME:  eval

# AWS region in which testgrinder operates
AWS_REGION:  us-east-1

# If true, force http requests to redirect to https; default: true
FORCE_SSL: false

# hostname for tg-app server to set; %i in it will be replaced with tg-app AWS instance id
# HOSTNAME:  tg-eval-app-%i

# domain that users will use to access testgrinder (and SSL certificate is issued for)
DOMAIN_WEB:  ec2-18-232-145-243.compute-1.amazonaws.com

# used to generate tokens embedded in account management emails, recommended lengths - 128 characters
DEVISE_SECRET_KEY:  7d8065a634c080677a0a6a3d0fe5699737fb4adff33fe724b9b016006afe7565168101bb1a80c04ef05f710c088bd1f54828c4bde08758242b1c67cf34d790ad

# added to user passwords prior to hashing, recommended lengths - 128 characters
DEVISE_PEPPER:  de613bf94647144f6912e73be6858328b632ff73bb021f8f5025f85db81a96becac3f3927c870aa36fa909b027452d35a685d76f000e68c2ff79d41d746a51bd

# used to encrypt cookies, recommended lengths - 128 characters
SECRET_KEY_BASE:  88175cf8a636c8ea6b00f43da47f02054bdc99016dd7f17c2967fceaaee847af214ce346b2075391b30ee77448d314afe014252ab0f38221ae73b542931d21c2

# used to encrypt sensitive values in the database, must be 32 characters long
DBDATA_SECRET_KEY:  0e9572e2e1b211c69aa1eb160280a002

# URI of the testgrinder database
MONGODB_URI:  mongodb://127.0.0.1:27017/tg_app_production

# uncomment to disable the local mongo database - advisable if you use a standalone database
# DISABLE_LOCAL_MONGODB:  true

# SMTP for testgrinder to use to send emails out
# SMTP_HOST:      <host>
# SMTP_PORT:      <port>
# SMTP_USERNAME:  <username>
# SMTP_PASSWORD:  <password>

# If you'd like to receive email notifications from Monit, specify To and From emails for Monit to use
# MONIT_NOTIFY_EMAIL:      <email of the Monit notifications recipient>

# timezone for the server; America/New_York is default
# TIMEZONE:  America/New_York

# specify to enable papertrail.com (log aggregation service) integration
# PAPERTRAIL:  <host>:<port>

# Provide to enable bugsnag.com (defect tracking) integration
# BUGSNAG_API_KEY:  <key>

ssl_cert.crt and ssl_private_key.key

testgrinder will configure its web server to use the ssl_cert.crt and ssl_private_key.key files as the source of its SSL certificate and the SSL certificate private key respectively. Make sure that the .env DOMAIN_WEB setting matches the domain for which the certificate is issued.

tg-app servers come with pre-generated ssl_cert.crt and ssl_private_key.key files containing a self-signed certificate. Using this certificate will result in a security warning when accessing testgrinder. Providing your own certificate is strongly recommended.

Providing Configuration Files via User Data on tg-app Launch

Instead of manually providing configuration files, you may provide a specially formatted User Data parameter as part of launching the tg-app AWS EC2 instances. If User Data is provided, tg-app, upon launch, will use it to extract the configuration files from it in the /home/testgrinder/tg-app/config/provision directory.

Generate User Data from Configuration Files

Once you have configuration files in the /home/testgrinder/tg-app/config/provision directory that you are happy with, it is an easy process to package them into User Data format. For that, run the export-user-data script and it will package the configuration files into the User Data format:

$ ssh ubuntu@my-tg-app
$ sudo su - testgrinder
$ cd tg-app
$ script/export-user-data my-user-data.yml

The resulting file - my-user-data.yml file - will have all configuration files in the /home/testgrinder/tg-app/config/provision directory packaged in User Data format.

Copy the generated User Data file off the tg-app server and keep it in a secure location. When you launch new tg-app instances you may supply this file as the User Data parameter during AWS EC2 instance launch and tg-app will extract the configuration files from it so you don't have to manually login to the newly launched server to finalize its configuration.

Editing the User Data file

The User Data is in a human readable format that can be edited if you need to adjust some settings or replace the SSL certificate before you launch a new tg-app instance. The User Data is in YAML format where keys are the filenames and values are the file contents:

filename1.ext: |
  content line 1
  content line 2
filename2.ext: |
  line 1
  line 2

Important notes:

• filenames must be followed by : (colon), then a space, and then | (vertical pipe/bar)

• each line of file contents must be preceded by two spaces

For example:

.env: |
  STAGE_NAME: eval
  AWS_REGION: us-east-1
  ...
ssl_cert.crt: |
  -----BEGIN CERTIFICATE-----
  MIIFNDCCAxwCCQCxAQy9xmU5FDANBgkqhkiG9w0BAQsFADBcMQswCQYDVQQGEwJV
  ...
  mZobNEu0lkHHe9/DkiErONGTULYr/ZK2OX5Lo8mqsbLWKSvzH2xdwg==
  -----END CERTIFICATE-----
ssl_private_key.key: |
  -----BEGIN PRIVATE KEY-----
  MIIJQgIBADANBgkqhkiG9w0BAQEFAASCCSwwggkoAgEAAoICAQDNL7ZD2wRhB55y
  ...
  FVX73NjAMYLJ0NZ3c2jnAOcnS9P1ow==
  -----END PRIVATE KEY-----

Note: the ellipses (...) above represent lines cut out for brevity. Do not include ... in your User Data.