Configuration

The following page is giving details about the environment variables you can set to adjust the behavior of your Datastore deployment.

Datastore configuration file

All configuration variables are available in this configuration file.

General

Environment variable prefix

You can prefix all environment variables by changing the value of DATASTORE_ENV_PREFIX. The default value is datastore. PORT environment variable can then be defined as DATASTORE_PORT or PORT.

ENV_FILE

Path of the configuration file to load in place of the one built from environment variables. The file must be a valid JSON file and respect the configuration file format.

PORT (3001)

Default HTTP port used to expose the Open API.

EXIT_TIMEOUT (1000)

milliseconds

Delay before exiting the program on SIGTERM, SIGINT or any crash. Having a delay helps the application to send last events or stack traces to observability layer.

API_DOC_SECRET (api-docs)

Path of the generated Open API specification. By default, the documentation will be available on the address: http://localhost:3001/api/api-docs.

Changing this value will help you having the specification available at a safer place. This specification is not secured by access tokens.

Access Tokens

Multiple access tokens can be defined for each role by separating them with a comma (,).

Examples

READ_ACCESS_TOKENS=abcd
READ_ACCESS_TOKENS=read:abcd
READ_ACCESS_TOKENS=read:abcd,read:efgh

caution

For security purpose, no token is defined by default. In order to start playing with the Datastore in local, you must define an ADMIN access token you will set in your local environment.

READ_ACCESS_TOKENS (none)

Authentication tokens having the READ permission.

DECRYPT_ACCESS_TOKENS (none)

Authentication tokens having the DECRYPT permission.

WRITE_ACCESS_TOKENS (none)

Authentication tokens having the WRITE permission.

ADMIN_ACCESS_TOKENS (none)

Authentication tokens having the ADMIN permission.

Data Encryption

SECURITY_ENCRYPTION_KEYS (none)

List of keys used to encrypt the data at rest. Must be used in conjonction with the encrypted_fields defined in the Model configuration.

Format

{
  all?: string[];             // Encryption keys available for all models
  [key: string]: string[];    // key = model name
}

SECURITY_ACTIVE_NUMBER_ENCRYPTION_KEYS (1)

Number of encryption keys used randomly to encrypt data at rest. First keys are considered as the active ones. Keys defined on the model level are used priorly generic all ones applied to all models. If more than one active key is available at a given time, the keys rotation must be done by adding number new keys equal to the value of SECURITY_ACTIVE_NUMBER_ENCRYPTION_KEYS.

Features

FEATURE_PROPERTY_IS_{X}

Model field definition for special properties: is_readonly, is_archived and is_deleted.

Default values are:

• FEATURE_PROPERTY_IS_READONLY: is_readonly
• FEATURE_PROPERTY_IS_ARCHIVED: is_archived
• FEATURE_PROPERTY_IS_DELETED: is_deleted

CORS Cross-Origin Resource Sharing

FEATURE_CORS_ENABLED (true)

Cross-Origin Resource Sharing (CORS) headers activation. In most cases, the deactivation of these security headers can be justified in a development environment. In any other case, other FEATURE_CORS_{X} configuration properties can be set.

Rules

Please read CORS Response and Request headers section in the Mozilla Developer Network (MDN) pages.

• FEATURE_CORS_ALLOW_CREDENTIALS for Access-Control-Allow-Credentials
• FEATURE_CORS_ALLOW_HEADERS for Access-Control-Allow-Headers
• FEATURE_CORS_ALLOW_METHODS for Access-Control-Allow-Methods
• FEATURE_CORS_ALLOW_ORIGIN for Access-Control-Allow-Origin
• FEATURE_CORS_EXPOSE_HEADERS for Access-Control-Expose-Headers
• FEATURE_CORS_REQUEST_HEADERS for Access-Control-Request-Headers
• FEATURE_CORS_REQUEST_METHOD for Access-Control-Request-Method

API Timeouts

Max delay defined in milliseconds before closing any HTTP request.

• FEATURE_API_TIMEOUT_MODELS_IN_MILLISECONDS (5000 = 5 seconds)
• FEATURE_API_TIMEOUT_AGGREGATE_IN_MILLISECONDS (30000 = 30 seconds)

The time response must be as low as possible. This timeout is measured on server level and does not take into account network latencies or SSL/TLS layer negociation. A high time response usually indicates a lack of MongoDB index.

FEATURE_API_TEMPLATES (false)

Expose example templates over HTTP API to start playing with basic features of the Datastore.

FEATURE_API_ADMIN (false)

Enable administration API to create a new model, update existing ones or apply any administration level action. Requests must have ADMIN level token credential.

FEATURE_API_AGGREGATE (false)

Enable aggregation API.

FEATURE_API_GRAPHQL (false)

Enable GraphQL API.

FEATURE_API_OPEN_API_ENABLED (true)

Enable OpenAPI specification validation on request and response level. Invalid response validation leads to a 500 error for the client and indicates that a data migration has not been performed after a Model contract breaking change.

FEATURE_API_OPENAPI_WARN_ON_INVALID_SPECIFICATION_ONLY (false)

If for some reason, contracts defining your models does not comply with the part of the JSON Schema respecting the OpenAPI 3.0 specification, you can disable the boot crash behavior and replace it with a warn message.

FEATURE_API_JSON_LIMIT (50mb)

Max size accepted for JSON request payload. The value must be compatible with ones supported by the bytes library ¹.

FEATURE_API_UPDATE_SPEC_ON_MODELS_CHANGE (false)

By default and for reliability reason, models available in the Datastore are loaded once during the boot phasis. Thus, any model creation or update results in a nil operation (aka noop).

Putting true to this variable is asking the Datastore to update its models definitions after a model creation or update.

Horizontally scaled deployment

Only the Datastore receiving the model creation or update request will update its own models definitions. As a consequence, Datastores horizontally scaled can be unsynced if this flag is used in production.

FEATURE_EVENTS_MAX_RETRY (3)

In async events API, this value is setting the max retry of an event after giving up and if possible putting it in the errors queue (AMQP).

FEATURE_MQTT_IS_ENABLED (false)

Enable the MQTT protocol communication.

FEATURE_AMQP_IS_ENABLED (false)

Enable the AMQP protocol communication.

FEATURE_MONGODB_MAX_TIME_MS (5000)

Max duration a MongoDB find query can stay alive.

FEATURE_MONGODB_EXPLAIN (false)

If true, Datastore will log information about detected slow queries.

FEATURE_MONGODB_SLOW_QUERY_THRESHOLD_IN_MILLISECONDS (1000)

Slow queries threshold in milliseconds. If FEATURE_MONGODB_EXPLAIN=true and a query is lasting more than FEATURE_MONGODB_SLOW_QUERY_THRESHOLD_IN_MILLISECONDS milliseconds, a detailed log will be displyed givin necessary information to create an index for this query.

DEFAULT_RETRY_DURATION_IN_MILLISECONDS (0)

If greater than 0, all models will have a concurrency tolerance on update specified to the given time duration in milliseconds.

FEATURE_DELETE_AFTER_ARCHIVE_DURATION_IN_SECONDS (14 days)

Minimum duration before accepting deleting an archived entity. If a deletion request is sent before this delay, a Entity archived too recently error will be thrown.

FEATURE_INIT_INTERNAL_MODELS (false)

The first time the Datastore is deployed, it must initialized its own internal models. This can be done to start the application once with FEATURE_INIT_INTERNAL_MODELS=true.

FEATURE_LOAD_ONLY_MODELS (none)

If multiple deployments are using the same database, you can specify which models must be loaded for each deployment. This is useful during Domain migrations or if some specific models require different configurations or scalability.

Example

FEATURE_LOAD_ONLY_MODELS='["users","metrics"]'

MongoDB

Name	Type	Default	Purpose
MONGO_URL	string	mongodb://localhost:27017/datastore	Connection string
MONGO_USE_UNIFIED_TOPOLOGY	true or false	true	Does MongoDB use the unified topology
MONGO_SSL	true or false	false	SSL active
MONGO_SSL_VALIDATE	true or false	false	SSL validation
MONGO_SSL_CERT	string	``	SSL certificate

---

List of environment varilables

name	default
ENV_FILE ✅	``
PORT ✅	3001
NODE_ENV	production
EXIT_TIMEOUT ✅	1000
READ_ACCESS_TOKENS ✅	``
DECRYPT_ACCESS_TOKENS ✅	``
WRITE_ACCESS_TOKENS ✅	``
ADMIN_ACCESS_TOKENS ✅	``
API_DOC_SECRET ✅	api-docs
SECURITY_ENCRYPTION_KEYS ✅	{}
SECURITY_ACTIVE_NUMBER_ENCRYPTION_KEYS ✅	1
FEATURE_PROPERTY_IS_READONLY ✅	is_readonly
FEATURE_PROPERTY_IS_ARCHIVED ✅	is_archived
FEATURE_PROPERTY_IS_DELETED ✅	is_deleted
FEATURE_CORS_ENABLED ✅
FEATURE_CORS_ALLOW_CREDENTIALS ✅
FEATURE_CORS_ALLOW_HEADERS ✅
FEATURE_CORS_ALLOW_METHODS ✅
FEATURE_CORS_ALLOW_ORIGIN ✅
FEATURE_CORS_EXPOSE_HEADERS ✅
FEATURE_CORS_REQUEST_HEADERS ✅
FEATURE_CORS_REQUEST_METHOD ✅
FEATURE_CACHE_ENABLED ❌
FEATURE_CACHE_SCOPE ❌	ds
FEATURE_API_TIMEOUT_MODELS_IN_MILLISECONDS ✅	5000
FEATURE_API_TIMEOUT_AGGREGATE_IN_MILLISECONDS ✅	30000
FEATURE_API_TEMPLATES ✅
FEATURE_API_ADMIN ✅
FEATURE_API_AGGREGATE ✅
FEATURE_API_GRAPHQL ✅
FEATURE_API_OPEN_API_ENABLED ✅
FEATURE_API_OPENAPI_WARN_ON_INVALID_SPECIFICATION_ONLY ✅
FEATURE_API_JSON_LIMIT ✅	50mb
FEATURE_API_UPDATE_SPEC_ON_MODELS_CHANGE ✅
EVENTS_MAX_RETRY ✅	3
FEATURE_MQTT_IS_ENABLED ✅	false
FEATURE_AMQP_IS_ENABLED ✅	false
FEATURE_MONGODB_MAX_TIME_MS ✅	5000
FEATURE_MONGODB_EXPLAIN ✅	false
FEATURE_MONGODB_SLOW_QUERY_THRESHOLD_IN_MILLISECONDS ✅	1000
DEFAULT_RETRY_DURATION_IN_MILLISECONDS ✅	0
FEATURE_DELETE_AFTER_ARCHIVE_DURATION_IN_SECONDS ✅	1209600
FEATURE_INIT_INTERNAL_MODELS ✅	false
FEATURE_LOAD_ONLY_MODELS ✅	null
GRAPHQL_HTTP_CONFIG	{}
GRAPHQL_OPENAPI_TO_GRAPHQL_CONFIG	{}
MQTT_NAMESPACE	``
MQTT_URL	mqtt://localhost:1883
MQTT_OPTIONS	{}
FEATURE_MQTT_GROUP	datastore
AMQP_NAMESPACE	``
AMQP_URL	amqp://guest:guest@localhost:5672
AMQP_OPTIONS	{}
AMQP_FAILOVER_RECONNECTION_TIMEOUT_IN_MILLISECONDS	1000
AMQP_CHANNEL_PREFETCH	100
AMQP_EXCHANGE_CONSUMER_NAME	datastore
AMQP_EXCHANGE_CONSUMER_TYPE	topic
AMQP_EXCHANGE_CONSUMER_OPTIONS	{}
AMQP_EXCHANGE_PRODUCER_NAME	datastore
AMQP_EXCHANGE_PRODUCER_TYPE	topic
AMQP_EXCHANGE_PRODUCER_OPTIONS	{}
AMQP_QUEUE_CONSUMER_NAME	datastore
AMQP_QUEUE_CONSUMER_OPTIONS	{}
AMQP_QUEUE_ERRORS_IS_ENABLED	false
AMQP_QUEUE_ERRORS_NAME	errors
AMQP_QUEUE_ERRORS_OPTIONS	{}
AMQP_HEADERS	{}
MONGO_WRITE_URL
MONGO_URL
MONGO_CONNECT_TIMEOUT_IN_MILLISECONDS	10000
MONGO_HEARTBEAT_FREQUENCY_IN_MILLISECONDS	1000
MONGO_MIN_HEARTBEAT_FREQUENCY_IN_MILLISECONDS	1000
MONGO_USE_UNIFIED_TOPOLOGY
MONGO_USE_NEW_URL_PARSER
MONGO_SERVER_API
MONGO_SSL
MONGO_SSL_VALIDATE
MONGO_USERNAME
MONGO_PASSWORD
MONGO_USERNAME
MONGO_PASSWORD
MONGO_WRITE_OPTIONS	{}
MONGO_READ_URL
MONGO_URL
MONGO_CONNECT_TIMEOUT_IN_MILLISECONDS	10000
MONGO_HEARTBEAT_FREQUENCY_IN_MILLISECONDS	1000
MONGO_MIN_HEARTBEAT_FREQUENCY_IN_MILLISECONDS	1000
MONGO_USE_UNIFIED_TOPOLOGY
MONGO_USE_NEW_URL_PARSER
MONGO_SERVER_API
MONGO_SSL
MONGO_SSL_VALIDATE
MONGO_USERNAME
MONGO_PASSWORD
MONGO_USERNAME
MONGO_PASSWORD
MONGO_READ_OPTIONS	{}
DATASTORE_CONFIGS	[]
OPENAPI_SPEC	{}

---

1. https://github.com/expressjs/body-parser#limit↩