Configuration

Ember Nexus API can be configured through environment variables (database connections, common options) and by providing a YML config file for lesser used settings.

A refactoring of the configuration process is planned in issue #463.

Environment variables

Ember Nexus specific variables:

ANONYMOUS_USER_UUID: The UUID of a user, which will be used if no token is supplied.
CYPHER_AUTH: Connection string for accessing the OpenCypher database, i.e. Neo4j.
MONGO_AUTH: Connection string for accessing the Mongo database.
ELASTIC_AUTH: Connection string for accessing the Elasticsearch database.
S3_ENDPOINT: URL of the S3-compatible storage API, e.g. http://minio:9000.
S3_ACCESS_KEY_ID: Access key ID used to authenticate against the S3-compatible storage API.
S3_SECRET_ACCESS_KEY: Secret access key used to authenticate against the S3-compatible storage API.
REDIS_AUTH: Connection string for accessing the Redis database.
RABBITMQ_AUTH: Connection string for accessing the RabbitMQ database.
VERSION: Variable containing the version of the currently running API software. Automatically set by the build process.
REFERENCE_DATASET_VERSION: Variable containing the version of the reference dataset used for validating features.
DISABLE_CRON: Set to true to disable the background tasks every API instance would otherwise run automatically. Defaults to false.

Framework specific variables:

See Symfony’s documentation for details.

Background tasks

Every API container instance runs the cron command automatically, every 5 minutes, for as long as the container is up - there is nothing to schedule externally, and running multiple instances in parallel is safe since the individual tasks (e.g. cron:reindex-files) consume their work from a shared RabbitMQ queue, so the same item is never processed twice regardless of how many instances happen to poll at once. Set the DISABLE_CRON environment variable to true on an instance to opt it out, e.g. to run cron on a different schedule yourself instead.

File storage buckets

Ember Nexus stores uploaded files in two separate S3-compatible buckets: file.S3UploadBucket holds chunks of resumable uploads still in progress, and file.S3StorageBucket holds files that have been fully attached to an element - see Uploads operate on temporary storage for how a file moves from one to the other. Because nothing in the upload bucket is meant to outlive its upload, and Ember Nexus already cleans up expired uploads itself (see Expiry in the upload reference and the background tasks above), operators can safely add a short S3 lifecycle/expiration policy to the upload bucket as an extra backstop. The storage bucket holds permanently retained files and should not have such a policy applied to it.

Ember Nexus does not create these buckets itself - they must already exist on the S3-compatible storage before the API starts, named exactly as configured (api-storage / api-upload by default). The Docker Compose example includes a minio-init container that creates both buckets on a fresh MinIO instance; without it (or an equivalent manual mc mb / console step) the healthcheck command fails and uploads and downloads do not work.

YML configuration

The configuration file must be mounted at /var/www/html/config/packages/ember_nexus.yaml.

Note: The file extension must be .yaml.

# Default configuration for extension with alias: "ember_nexus"
ember_nexus:

  # Affects how many elements can be returned in collection responses.
  pageSize:

    # Minimum number of elements which are always returned, if they exist.
    min: 5

    # Default number of elements which are returned if they exist.
    default: 25

    # Maximum number of elements which are returned in a single response. Should not be way more than 100, as performance problems may arise.
    max: 100

  # Handles the /register endpoint.
  register:

    # If true, the /register endpoint is active and anonymous users can create accounts.
    enabled: true

    # The property name of the identifier. Identifier must be unique across the API, usually the email.
    uniqueIdentifier: email

    # Either false or a regex for checking the identifier content.
    uniqueIdentifierRegex: false

  # Configures settings related to the execution of expressions
  expression:

    # If true, expressions are executed.
    enabled: true

    # Minimum length for executable expressions to trigger a warning in the logs.
    warningLength: 512

    # Maximum length for executable expressions. Exceeding the limit will throw an exception.
    maxLength: 10240

  # Configures the /instance-configuration endpoint.
  instanceConfiguration:

    # If true, enables the endpoint. If false, 403 error messages are returned.
    enabled: true

    # If false, the version number is omitted.
    showVersion: true

  # Configures token settings.
  token:

    # Minimum lifetime of created tokens.
    minLifetimeInSeconds: 1800

    # Default lifetime of created tokens.
    defaultLifetimeInSeconds: 10800

    # Maximum lifetime of created tokens. Can be set to false to disable maximum limit.
    maxLifetimeInSeconds: 34214400

    # Expired tokens will be deleted after defined time. Can be set to false to disable auto delete feature.
    tokenDeleteExpiredTokensAutomaticallyInSeconds: 1209600

  # Configures the cache.
  cache:

    # Seed used to generate Etag values. Changing it invalidates all data cached by clients.
    etagSeed: ''

    # Maximum number of items in a collection for which to generate Etags. Bigger collection do not contain Etags due to performance problems.
    etagUpperLimitInCollectionEndpoints: 100

  # Configures feature flags.
  featureFlag:

    # If true, the original behavior of some user endpoints in versions before 0.1.6 will no longer be supported. Old behavior will be dropped with version 0.2.0. See GitHub issue #280.
    280_OldUniqueUserIdentifierDisabled: false

  # Configures behavior related to files.
  file:

    # Maximum supported file size in bytes. Note: Upstream services like S3 have limits of their own (5TB).
    maxFileSizeInBytes: 10737418240

    # Number of seconds after which unfinished uploads are expired.
    uploadExpiresInSecondsAfterFirstRequest: 10800

    # Number of digits for the upload chunk counter. Number of max chunks can be limited by upstream services, e.g. AWS can only support up to 10.000 chunks, i.e. a chunk digits length of 4.
    uploadChunkDigitsLength: 4

    # Minimum size in bytes of uploaded chunks. Limited by the S3 provider, e.g. AWS requires that chunks are at least 5 MiB big.
    uploadMinChunkSizeInBytes: 5242880

    # Maximum size in bytes of uploaded chunks. Limited by the S3 provider, Caddy and the PHP configuration.
    uploadMaxChunkSizeInBytes: 105906176

    # Name of the S3 bucket used for storage of files.
    S3StorageBucket: api-storage

    # Name of the S3 bucket used for temporary storage of uploads.
    S3UploadBucket: api-upload

    # Number of levels (folders) used within the S3 storage bucket.
    S3StorageBucketLevels: 3

    # Number of characters used for each level (folder) in the S3 storage bucket.
    S3StorageBucketLevelLength: 2

    # Number of levels (folders) used within the S3 upload bucket.
    S3UploadBucketLevels: 2

    # Number of characters used for each level (folder) in the S3 upload bucket.
    S3UploadBucketLevelLength: 2

This file can be downloaded directly .