flyrain commented on code in PR #4464: URL: https://github.com/apache/polaris/pull/4464#discussion_r3282999825
########## 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 +to be running. +{{< /alert >}} Using Docker: ```bash docker run --rm -it \ + --network=host \ Review Comment: `--network=host` is Linux-only. On macOS/Windows Docker Desktop, point users at `host.docker.internal` or a user-defined network. Same applies to the start, maintenance-run, maintenance-info, and maintenance-log examples. ########## 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 +`polaris.realm-context.realms=polaris` (lowercase) when starting the server. A mismatch will +cause `Unknown realm` errors at runtime. +{{< /alert >}} + +### MongoDB Atlas For MongoDB Atlas deployments, use the `mongodb+srv://` connection string format: ```properties polaris.persistence.type=nosql polaris.persistence.nosql.backend=MongoDb -quarkus.mongodb.database=polaris +quarkus.mongodb.database=<database-name> quarkus.mongodb.connection-string=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority +polaris.realm-context.realms=<realm-name> ``` -## MongoDB Replica Set Configuration +### TLS/SSL -For replica set deployments: +For encrypted connections, add `tls=true` to the connection string: ```properties -polaris.persistence.type=nosql -polaris.persistence.nosql.backend=MongoDb -quarkus.mongodb.database=polaris -quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<rs-name>&authSource=admin +quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<rs-name>&tls=true ``` Review Comment: Worth a one-liner pointing at Quarkus TLS options (CA bundles, hostname verification) so users don't blindly add `tlsAllowInvalidCertificates=true`. -- 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]
