dimas-b commented on code in PR #4464: URL: https://github.com/apache/polaris/pull/4464#discussion_r3278108892
########## site/content/in-dev/unreleased/metastores/nosql-mongodb.md: ########## @@ -82,27 +98,33 @@ quarkus.mongodb.write-concern.safe=true quarkus.mongodb.read-preference=primaryPreferred ``` -For TLS/SSL connections, add `tls=true` to the connection string: - -```properties -quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port>/?tls=true -``` - -For more details on available MongoDB configuration options, please refer to the [Quarkus MongoDB configuration reference](https://quarkus.io/guides/mongodb#configuration-reference). +For the full list of available options, refer to the +[Quarkus MongoDB configuration reference](https://quarkus.io/guides/mongodb#configuration-reference). ## Bootstrapping Polaris -Before using Polaris with the MongoDB backend, you must bootstrap the metastore to create the necessary collections and initial realm. This is done using the [Admin Tool]({{% ref "../admin-tool" %}}). +Before starting Polaris for the first time, you must bootstrap the metastore. This creates +the necessary MongoDB collections (`objs` and `refs`) and an initial realm with root +credentials. Bootstrapping is a one-time operation performed using the +[Admin Tool]({{% ref "../admin-tool" %}}). + +{{< alert note >}} +The bootstrap command connects directly to MongoDB and does not require the Polaris server Review Comment: This is already implied by the paragraph above 🤷 ########## site/content/in-dev/unreleased/metastores/nosql-mongodb.md: ########## @@ -26,51 +26,67 @@ weight: 200 The MongoDB backend is currently in **beta**. {{< /alert >}} -This implementation uses MongoDB as the persistence backend and leverages the Quarkus MongoDB extension for connection management. Configuration can be done through environment variables or JVM -D flags at startup. +Polaris supports MongoDB as a persistence backend via the Quarkus MongoDB extension. +Configuration is provided through environment variables or JVM `-D` flags at startup. -## Basic Configuration +For production deployments, MongoDB must be running as a **replica set** (or via MongoDB Atlas). +A single-node standalone MongoDB instance is not supported for production use, as Polaris +requires replica set semantics for its transaction model. Review Comment: I would not say that Polaris _requires_ "replica set semantics" 🤷 ########## site/content/in-dev/unreleased/metastores/nosql-mongodb.md: ########## @@ -26,51 +26,67 @@ weight: 200 The MongoDB backend is currently in **beta**. {{< /alert >}} -This implementation uses MongoDB as the persistence backend and leverages the Quarkus MongoDB extension for connection management. Configuration can be done through environment variables or JVM -D flags at startup. +Polaris supports MongoDB as a persistence backend via the Quarkus MongoDB extension. +Configuration is provided through environment variables or JVM `-D` flags at startup. -## Basic Configuration +For production deployments, MongoDB must be running as a **replica set** (or via MongoDB Atlas). +A single-node standalone MongoDB instance is not supported for production use, as Polaris +requires replica set semantics for its transaction model. -Using environment variables: +## Prerequisites -```properties -POLARIS_PERSISTENCE_TYPE=nosql -POLARIS_PERSISTENCE_NOSQL_BACKEND=MongoDb -QUARKUS_MONGODB_DATABASE=polaris -QUARKUS_MONGODB_CONNECTION_STRING=mongodb://<username>:<password>@<host>:<port> -``` +- A running MongoDB replica set (minimum 3 nodes recommended) or a MongoDB Atlas cluster Review Comment: What is the rationale for the 3 node recommendation? ########## site/content/in-dev/unreleased/metastores/nosql-mongodb.md: ########## @@ -26,51 +26,67 @@ weight: 200 The MongoDB backend is currently in **beta**. {{< /alert >}} -This implementation uses MongoDB as the persistence backend and leverages the Quarkus MongoDB extension for connection management. Configuration can be done through environment variables or JVM -D flags at startup. +Polaris supports MongoDB as a persistence backend via the Quarkus MongoDB extension. +Configuration is provided through environment variables or JVM `-D` flags at startup. -## Basic Configuration +For production deployments, MongoDB must be running as a **replica set** (or via MongoDB Atlas). +A single-node standalone MongoDB instance is not supported for production use, as Polaris +requires replica set semantics for its transaction model. -Using environment variables: +## Prerequisites -```properties -POLARIS_PERSISTENCE_TYPE=nosql -POLARIS_PERSISTENCE_NOSQL_BACKEND=MongoDb -QUARKUS_MONGODB_DATABASE=polaris -QUARKUS_MONGODB_CONNECTION_STRING=mongodb://<username>:<password>@<host>:<port> -``` +- A running MongoDB replica set (minimum 3 nodes recommended) or a MongoDB Atlas cluster +- Network connectivity from the Polaris server to all MongoDB replica set members +- The `apache/polaris-admin-tool` Docker image or the standalone JAR, for bootstrapping + +## Production Configuration -Using properties file: +### Replica Set + +For a self-managed MongoDB replica set, configure Polaris with all replica set member +hostnames in the connection string: ```properties polaris.persistence.type=nosql polaris.persistence.nosql.backend=MongoDb -quarkus.mongodb.database=polaris -quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port> +quarkus.mongodb.database=<database-name> +quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<rs-name>&authSource=admin ``` -## MongoDB Atlas Configuration +You must also tell Polaris which realms to serve at startup. The realm name must exactly +match the name used during bootstrapping (case-sensitive): Review Comment: This is placed in-between different Mongo config options... which is kind of odd. Also the tone of this phrase could probably be improved. ########## site/content/in-dev/unreleased/metastores/nosql-mongodb.md: ########## @@ -26,51 +26,67 @@ weight: 200 The MongoDB backend is currently in **beta**. {{< /alert >}} -This implementation uses MongoDB as the persistence backend and leverages the Quarkus MongoDB extension for connection management. Configuration can be done through environment variables or JVM -D flags at startup. +Polaris supports MongoDB as a persistence backend via the Quarkus MongoDB extension. +Configuration is provided through environment variables or JVM `-D` flags at startup. -## Basic Configuration +For production deployments, MongoDB must be running as a **replica set** (or via MongoDB Atlas). +A single-node standalone MongoDB instance is not supported for production use, as Polaris +requires replica set semantics for its transaction model. -Using environment variables: +## Prerequisites -```properties -POLARIS_PERSISTENCE_TYPE=nosql -POLARIS_PERSISTENCE_NOSQL_BACKEND=MongoDb -QUARKUS_MONGODB_DATABASE=polaris -QUARKUS_MONGODB_CONNECTION_STRING=mongodb://<username>:<password>@<host>:<port> -``` +- A running MongoDB replica set (minimum 3 nodes recommended) or a MongoDB Atlas cluster +- Network connectivity from the Polaris server to all MongoDB replica set members +- The `apache/polaris-admin-tool` Docker image or the standalone JAR, for bootstrapping + +## Production Configuration -Using properties file: +### Replica Set + +For a self-managed MongoDB replica set, configure Polaris with all replica set member +hostnames in the connection string: ```properties polaris.persistence.type=nosql polaris.persistence.nosql.backend=MongoDb -quarkus.mongodb.database=polaris -quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port> +quarkus.mongodb.database=<database-name> +quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<rs-name>&authSource=admin ``` -## MongoDB Atlas Configuration +You must also tell Polaris which realms to serve at startup. The realm name must exactly +match the name used during bootstrapping (case-sensitive): + +```properties +polaris.realm-context.realms=<realm-name> +``` + +{{< alert warning >}} +The realm name is case-sensitive. If you bootstrap a realm as `polaris`, you must configure Review Comment: This is not specific to Mongo. It is probably best to mention this on the Admin Tool page rather than here. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
