MongoDB

Document-Based Storage is an architectural abstraction in the Nuxeo Platform that allows the storage of documents in a document-oriented store, for instance NoSQL databases.

An implementation is available for MongoDB.

Nuxeo supports the following MongoDB version:

MongoDB 8

Installation

When using MongoDB 3.2 or higher the WiredTiger storage engine is the default storage engine.
Please follow this documentation if you’re running on MongoDB 3.0 to activate this storage engine for better performance of write operations.

Nuxeo stores its data in a MongoDB database under the default collection. The name of the collection is the Nuxeo repository name. If you have more than one repository configured, other collections with the names of these repositories will be used for storage.

By default MongoDB doesn't require authentication, but you can enable the client access control and create a user with the dbOwner role.

Nuxeo Configuration

To activate MongoDB document and directories storage (as of after Nuxeo FT 9.2), add the mongodb template to your existing list of templates (nuxeo.templates) in nuxeo.conf. Including the mongodb-audit template that will also activate audit storage.

nuxeo.templates=default,mongodb,mongodb-audit

If you are not using the MongoDB extension addon for previous versions of Nuxeo, you must keep the template corresponding to your SQL database in nuxeo.templates. For instance you could have:

nuxeo.templates=postgresql,mongodb

or

nuxeo.templates=default,mongodb

The following properties are available in nuxeo.conf:

nuxeo.mongodb.server=mongodb://example1.com,example2.com,example3.com/?maxPoolSize=200

TLS/SSL Configuration

If you have chosen to configure TLS/SSL then you can set up Nuxeo using nuxeo.conf with the following properties:

nuxeo.mongodb.ssl=true
nuxeo.mongodb.truststore.path
nuxeo.mongodb.truststore.password
nuxeo.mongodb.truststore.type
nuxeo.mongodb.keystore.path
nuxeo.mongodb.keystore.password
nuxeo.mongodb.keystore.type

See the Trust Store and Key Store Configuration page for more.

DocumentDB

DocumentDB is compatible with MongoDB. Therefore, it can be used by Nuxeo as a backend, like MongoDB, but with a few limitations. A DocumentDB deployment is configured exactly like a MongoDB one: it uses the same mongodb template and the same nuxeo.mongodb.* properties described above. Only the differences are detailed below.

The following DocumentDB flavors have been validated with Nuxeo:

• Amazon DocumentDB, both instance-based clusters and elastic clusters
• Azure DocumentDB
• The open source DocumentDB documentdb-local Docker image, which is convenient for local development

Limitations

Because DocumentDB does not implement all MongoDB features, the following limitations apply:

• No repository-level fulltext search - Fulltext content is still extracted and remains searchable through Elasticsearch or OpenSearch, but the fulltext search performed directly by the repository (MongoDB) is not available and must be disabled (see the configuration below).
• No retryable writes - Retryable writes must be disabled in the connection string (see the configuration below).
• Limited number of concurrent cursors - The maximum number of cursors open at any given time depends on the chosen DocumentDB service and instance type. Refer to your provider's documentation for the applicable quota.

Nuxeo also transparently handles two other differences, so no configuration is required for them:

• Unsupported index options - DocumentDB rejects some index options (such as partialFilterExpression, hidden, collation, storageEngine and wildcardProjection, which also covers hashed indexes). When Nuxeo creates its indexes at startup and the database rejects an unsupported option, it logs a warning and automatically retries the index creation without the unsupported options. This is expected and does not prevent startup.
• Explicit collection creation - DocumentDB Elastic clusters do not support implicit collection creation. Nuxeo creates the required collections explicitly before creating their indexes.

Other differences documented by the providers should not affect Nuxeo. For reference, see the Amazon DocumentDB Functional Differences and supported MongoDB APIs.

DocumentDB Configuration

Use the same mongodb template as for MongoDB and add the DocumentDB-specific settings in nuxeo.conf:

nuxeo.templates=mongodb
# Point to your DocumentDB cluster and disable retryable writes
nuxeo.mongodb.server=mongodb://<USER>:<PASSWORD>@<DOCUMENTDB_HOST>:27017/?retryWrites=false
# Disable repository (MongoDB) fulltext search, use Elasticsearch/OpenSearch instead
nuxeo.fulltext.search.disabled=true

org.quartz.jobStore.mongoOptionUseServerDefaultWriteConcern=true

DocumentDB is usually accessed over TLS. See the TLS/SSL Configuration section above for the related nuxeo.mongodb.ssl and trust store / key store properties. All other MongoDB configuration options (connection pool, database name, directories, audit, and so on) apply unchanged.

Hotfixes and indexes

Since LTS 2021 (NXP-29261) indexes are defined in document schemas and created during Nuxeo start. This is fine when starting from scratch, but it is not recommended on existing instance with large amount of documents, because creating an index is an heavy operation that can timeout or impact the MongoDB performance.

Some hotfixes may add missing or needed indexes to improve the overall performances of the platform. By default, a nuxeo server restarting after having installed an Hotfix defining a new index will try to create these indexes if not existing.

On instances with large repository:

• It is recommended to create the new indexes defined by an Hotfix prior to restarting the server. Each Hotfixes Installation Notes provides the command in order to create manually any new indexes for this matter.
• The auto create index on start option could be disabled with the nuxeo conf property nuxeo.db.indexes.create=false as long as the Hotfixes Installation Notes are carefully reviewed in order to manually create the needed indexes.

GridFS

It is possible to use MongoDB's GridFS mechanism to store binary files inside MongoDB instead of the default filesystem mechanism of Nuxeo. This is activated by adding gridfsbinaries to the templates, for instance:

nuxeo.templates=mongodb,gridfsbinaries

When doing this, binaries will be stored in the default.fs GridFS bucket, which means that in native MongoDB the collections default.fs.files and default.fs.chunks will be used. See the GridFS Reference for more details about MongoDB's GridFS implementation.

Connection Pool Configuration

Nuxeo has MongoDBConnectionService to instantiate MongoDB connections in the platform. This service holds all connections to MongoDB. By default, a contribution with id default will be contributed to the Nuxeo Platform, filled with nuxeo.mongodb.server and nuxeo.mongodb.dbname from nuxeo.conf.

If the service doesn't have a registered connection for the given id, it will return the default one.

You can customize the connections used depending on the feature. To do so, you need to contribute a connection to the service as below:

<component name="[COMPONENT_NAME]">

  <extension target="org.nuxeo.runtime.mongodb.MongoDBComponent" point="connection">
    <connection id="[CONNECTION_ID]">
      <server>mongodb://...</server>
      <dbname>...</dbname>
    </connection>
  </extension>

</component>

Here's a list of how features resolve their connection: