Note: This page is for internal Ensign development and will probably not be very useful to Ensign users.

Ensign services are primarily configured using environment variables and will respect dotenv files in the current working directory. The canonical reference of the configuration for an Ensign service is the config package of that service (described below). This documentation enumerates the most important configuration variables, their default values, and any hints or warnings about how to use them.

Required Configuration
If a configuration parameter does not have a default value that means it is required and must be specified by the user! If the configuration parameter does have a default value then that environment variable does not have to be set.

Ensign

The Ensign node is a replica of the Ensign eventing system. Its environment variables are all prefixed with the ENSIGN_ tag. The primary configuration is as follows:

Monitoring

Ensign uses Prometheus for metrics and observability. The Prometheus metrics server is configured as follows:

Storage

The Ensign storage configuration defines on disk where Ensign keeps its data. Configure storage as follows:

Note that the Ensign data path must be to a directory. If the directory does not exist, it is created. An error occurs if the path is to a file or the process doesn’t have permissions to access the directory. Ensign will open two different data stores in the data path: one for metadata and the other to store event data locally.

If the testing flag is set to true, a mock store is created that can be used in unit and integration tests.

Authentication

Ensign uses Quarterdeck to authenticate and authorize requests. This configuration defines how Ensign accesses public keys for JWT verification and how the authentication interceptor behaves.

Sentry

Ensign uses Sentry to assist with error monitoring and performance tracing. Configure Ensign to use Sentry as follows:

|

Sentry is considered enabled if a DSN is configured. Performance tracing is only enabled if Sentry is enabled and track performance is set to true. If Sentry is enabled, an environment is required, otherwise the configuration will be invalid.

Generally speaking, Ensign should enable Sentry for panic reports but should not enable performance tracing as this slows down the server too much. Note also that the sentry.Config object has a field Repanic that should not be set by the user. This field is used to manage panics in chained interceptors.

Tenant

The Tenant API powers the user front-end for tenant management and configuration. Its environment variables are all prefixed with the TENANT_ tag. The primary configuration is as follows:

Authentication

Tenant uses Quarterdeck to authenticate and authorize requests. The following configuration defines how Tenant validates JWT tokens passed in from the user that were created by Quarterdeck and secures cookies:

Database

Tenant connects to a replicated trtl database for its data storage; the trtl connection is configured as follows:

Quarterdeck

Tenant connects directly to Quarterdeck in order to send pass-through requests from the user (e.g. for registration, login, etc). This is separate from the authentication configuration used in middleware as this configuration is used to setup a Quarterdeck API client.

SendGrid

Tenant uses SendGrid to assist with email notifications. Configure Tenant to use SendGrid as follows:

SendGrid is considered enabled if the SendGrid API Key is set. The from and admin email addresses are required if SendGrid is enabled.

If the Ensign List ID is configured then Tenant will add the contact requesting private beta access to that list, otherwise it will simply add the contact to “all contacts”.

Sentry

Tenant uses Sentry to assist with error monitoring and performance tracing. Configure Tenant to use Sentry as follows:

Sentry is considered enabled if a DSN is configured. Performance tracing is only enabled if Sentry is enabled and track performance is set to true. If Sentry is enabled, an environment is required, otherwise the configuration will be invalid.

Note also that the sentry.Config object has a field Repanic that should not be set by the user. This field is used to manage panics in chained interceptors.

Quarterdeck

The Quarterdeck API handles authentication and authorization as well as API keys and billing management for the Ensign managed service. Its environment variables are all prefixed with the QUARTERDECK_ tag. The primary configuration is as follows:

SendGrid

Quarterdeck uses SendGrid to assist with email notifications. Configure Quarterdeck to use SendGrid as follows:

SendGrid is considered enabled if the SendGrid API Key is set. The from and admin email addresses are required if SendGrid is enabled.

If the Ensign List ID is configured then Quarterdeck will add the contact to that list to ensure they receive marketing emails about Ensign.

Rate Limit

In order to prevent brute force attacks on the Quarterdeck system we’ve implemented a rate limiting middleware to prevent abuse. Rate limiting is configured as follows:

It is strongly recommended that the default configuration is used.

Database

Quarterdeck uses a Raft replicated Sqlite3 database for authentication. The URI should have the scheme sqlite3:// and then a path to the database. For a relative path, use sqlite3:///path/to/relative.db and for an absolute path use sqlite3:////path/to/absolute.db.

Tokens

To create an environment variable that is a map[string]string use a string in the following form:

key1:value1,key2:value2

The token keys should be ULIDs keys (for ordering) and a path value to the key pair to load from disk. Generally speaking there should be two keys - the current key and the most recent previous key, though more keys can be added for verification. Only the most recent key will be used to issue tokens, however. For example, here is a valid key map:

01GECSDK5WJ7XWASQ0PMH6K41K:/data/keys/01GECSDK5WJ7XWASQ0PMH6K41K.pem,01GECSJGDCDN368D0EENX23C7R:/data/keys/01GECSJGDCDN368D0EENX23C7R.pem

Future Feature
Note that in the future quarterdeck will generate its own keys and will not need them to be set as in the configuration above.

Reporting

Ensign has a Daily PLG report that is sent to the Rotational admins for product led growth. This reporting tool is configured as follows:

Sentry

Quarterdeck uses Sentry to assist with error monitoring and performance tracing. Configure Quarterdeck to use Sentry as follows:

Sentry is considered enabled if a DSN is configured. Performance tracing is only enabled if Sentry is enabled and track performance is set to true. If Sentry is enabled, an environment is required, otherwise the configuration will be invalid.

Note also that the sentry.Config object has a field Repanic that should not be set by the user. This field is used to manage panics in chained interceptors.

Beacon

A React app delivers Beacon, the Ensign UI. Its environment variables are all prefixed with the REACT_APP tag. The primary configuration is as follows:

API Information

Connection information for the backend is specified as follows:

Google Analytics

The React app uses Google Analytics to monitor website traffic. Configure the React app to use Google Analytics as follows:

Sentry

The React app uses Sentry to assist with error monitoring and performance tracing. Configure the React app to use Sentry as follows: