Correct Docker and client setup instructions

documentdb-local/index.md

@@ -27,17 +27,32 @@ docker pull ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0
 To run the container, use `docker run`. Afterwards, use `docker ps` to validate that the container is running.
 
 ```bash
-docker run -dt -p 10260:10260 --name docdb ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 --username demo --password test
+read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME
+read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD
+printf '\n'
+export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD
+
+docker run -dt -p 127.0.0.1:10260:10260 --name docdb \
+  ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \
+  --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
+  --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"
 
 
 docker ps
 ```
 
 ```output
-CONTAINER ID   IMAGE                                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                                      NAMES
-5aff734a3591   ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0                        "/bin/bash -c '/home…"   5 seconds ago   Up 4 seconds   0.0.0.0:10260->10260/tcp, :::10260->10260/tcp                                                              docdb
+CONTAINER ID   IMAGE                                                                             COMMAND                  CREATED         STATUS         PORTS                              NAMES
+5aff734a3591   ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0                        "/bin/bash -c '/home…"   5 seconds ago   Up 4 seconds   127.0.0.1:10260->10260/tcp       docdb
 ```
 
+> The prompts export the credentials for the later client examples, and the guards
+> prevent an empty value from falling through to the image's public defaults. If you
+> open a new shell, set both variables again. The loopback binding makes the gateway
+> reachable only from this host. To allow remote clients, change it to
+> `-p 10260:10260` only after restricting the port with a firewall and configuring a
+> certificate that remote clients can validate.
+>
 > This container writes its database to `/data`, which the image declares as a Docker volume. The command above mounts nothing there, so each `docker run` gets a fresh anonymous volume: the data does not survive re-creating the container, and the old volume is left behind on the host until you prune it. Mount a named volume - `-v documentdb-data:/data` - to persist it. See `--data-path` in the table below.
 
 ### Wait for the container to be ready
@@ -59,7 +74,11 @@ First start typically takes a few tens of seconds. If the command has not return
 > The DocumentDB gateway endpoint is available on port `10260` by default. To access this with `mongosh`, run:
 
 ```bash
-mongosh "mongodb://demo:test@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true"
+mongosh localhost:10260 \
+  -u "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
+  -p "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  --authenticationMechanism SCRAM-SHA-256 \
+  --tls --tlsAllowInvalidCertificates
 ```
 
 ```output
@@ -83,7 +102,7 @@ The following table summarizes the available Docker commands for configuring the
 | Print the settings to stdout from the container | `--help`, `-h` | N/A | N/A | N/A | Display information on available configuration |
 | Specify the username for DocumentDB. | `--username [value]` | Overrides `USERNAME` environment variable | STRING | `default_user` | Username for DocumentDB. It may not be an internal DocumentDB role name, and it may not begin with `documentdb`, `citus`, `pg`, or `internal_role` (case-insensitive). The container rejects a reserved name and exits before starting anything. |
 | Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | `Admin100` | Password for DocumentDB. Always set this explicitly. The built-in default is well known, and anyone who can reach the published port can authenticate with it. |
-| The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `DOCUMENTDB_PORT` environment variable | INT | `10260` | The port needs to be published - for example, using `-p 10260:10260`. |
+| The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `DOCUMENTDB_PORT` environment variable | INT | `10260` | The port needs to be published. For local use, bind only to loopback - for example, `-p 127.0.0.1:10260:10260`. To use host port `27017` without changing the gateway port, publish `-p 127.0.0.1:27017:10260`; add `--documentdb-port 27017` only when changing the container-side port too. |
 | Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | Data is not persisted unless you mount a volume at this path - for example, `-v documentdb-data:/data`. To use a different directory, set the mount and the flag together, keeping in mind that they go on opposite sides of the image name: `-v` / `--mount` is a `docker run` option and comes before it, `--data-path` is a container argument and comes after it. See the example below the table. |
 | Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | The PostgreSQL role used to create the admin user. The cluster this image initializes has a single superuser role, `documentdb`, so leave this at the default: any other value fails with `role "<value>" does not exist` after PostgreSQL has already initialized, and the container exits. |
 | Specify whether to start the PostgreSQL server. | `--start-pg [value]` | Overrides `START_POSTGRESQL` environment variable | `true`, `false` | `true` | Set this to `false` only when you are pointing the gateway at a PostgreSQL server you run yourself; the container then expects one to be reachable on `--pg-port`. |
@@ -106,11 +125,13 @@ A complete `docker run` showing where each kind of option goes - Docker options
 
 ```bash
 docker run -dt \
-  -p 10260:10260 \
+  -p 127.0.0.1:10260:10260 \
   -v documentdb-data:/data \
   --name docdb \
   ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \
-  --username demo --password test --init-data true
+  --username "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
+  --password "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  --init-data true
 ```
 
 ## Built-in sample data
@@ -161,20 +182,25 @@ To keep the same certificate across re-creating the container, pin the location
 
 ```bash
 docker run -dt \
-  -p 10260:10260 \
+  -p 127.0.0.1:10260:10260 \
   -v documentdb-data:/data \
   -e DOCUMENTDB_TLS_STATE_DIR=/data/tls \
   --name docdb \
   ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \
-  --username demo --password test
+  --username "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
+  --password "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}"
 ```
 
 Point it inside the data directory rather than at a volume of its own: the entrypoint takes ownership of the data directory on every start, whereas a separate volume is created root-owned and the gateway - which runs as an unprivileged user - cannot write its key there. The trade-off is that the same step runs `chmod -R 750` over that directory, so from the second start onwards the private key is group-readable rather than owner-only, and it is included in any backup of the data volume.
 
 ### Use the certificate with mongosh
 
 ```bash
-mongosh localhost:10260 -u demo -p test --authenticationMechanism SCRAM-SHA-256 --tls --tlsCAFile ~/documentdb-cert.pem
+mongosh localhost:10260 \
+  -u "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
+  -p "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  --authenticationMechanism SCRAM-SHA-256 \
+  --tls --tlsCAFile ~/documentdb-cert.pem
 ```
 
 ```output

getting-started/mongo-shell-quickstart.md

@@ -24,13 +24,22 @@ docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest
 # Tag the image for convenience
 docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb
 
+read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME
+read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD
+printf '\n'
+export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD
+
 # Run the container with your chosen username and password
-docker run -dt -p 10260:10260 --name documentdb-container documentdb --username <YOUR_USERNAME> --password <YOUR_PASSWORD>
+docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb \
+  --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
+  --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"
 ```
 
-> **Note:** Replace `<YOUR_USERNAME>` and `<YOUR_PASSWORD>` with your desired credentials. Always set them explicitly: if you omit them the container starts with the built-in `default_user` / `Admin100`, which are public and let anyone who can reach the published port authenticate as the admin user.
+> **Note:** The prompts export the credentials for the `mongosh` command below. The guards reject empty values so the container cannot fall through to the public `default_user` / `Admin100` defaults. If you open a new shell, set both environment variables again.
+>
+> **Network note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate.
 >
-> **Port note:** Port `10260` is used by default to avoid conflicts with other local database services. You can use port `27017` (the standard MongoDB port) or any other available port — update the port in the `docker run` command and your connection string accordingly.
+> **Port note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port.
 
 Confirm the container is running:
 
@@ -51,7 +60,11 @@ If this has not returned after a couple of minutes, the container probably exite
 DocumentDB Local accepts TLS connections on the gateway port and requires authentication. The container generates a self-signed certificate on first start and reuses it thereafter, so the simplest local connection skips certificate validation with `tlsAllowInvalidCertificates=true`.
 
 ```bash
-mongosh "mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true"
+mongosh localhost:10260 \
+  -u "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
+  -p "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  --authenticationMechanism SCRAM-SHA-256 \
+  --tls --tlsAllowInvalidCertificates
 ```
 
 For instructions on installing the generated certificate so you can validate it normally, see [DocumentDB Local](https://documentdb.io/docs/documentdb-local/).

getting-started/nodejs-setup.md

@@ -26,17 +26,27 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance
    # Tag the image for convenience
    docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb
 
+   read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME
+   read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD
+   printf '\n'
+   export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD
+
    # Run the container with your chosen username and password
-   docker run -dt -p 10260:10260 --name documentdb-container documentdb --username <YOUR_USERNAME> --password <YOUR_PASSWORD>
-   docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest
+   if docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb \
+     --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
+     --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"; then
+     docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest
+   fi
    ```
 > **Note:** During the transition to the Linux Foundation, Docker images may still be hosted on Microsoft's container registry. These will be migrated to the new DocumentDB organization as the transition completes.
 >
-> **Note:** Replace `<YOUR_USERNAME>` and `<YOUR_PASSWORD>` with your desired credentials. Always set them explicitly: if you omit them the container starts with the built-in `default_user` / `Admin100`, which are public and let anyone who can reach the published port authenticate as the admin user.
+> **Note:** The prompts export the credentials for the Node.js example below. The guards reject empty values so the container cannot fall through to the public `default_user` / `Admin100` defaults. If you skip this Docker setup or open a new shell, set both environment variables before running Node.js.
 >
 > **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done`
 >
-> **Port Note:** Port `10260` is used by default in these instructions to avoid conflicts with other local database services. You can use port `27017` (the standard MongoDB port) or any other available port if you prefer. If you do, be sure to update the port number in both your `docker run` command and your connection string accordingly.
+> **Network Note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate.
+>
+> **Port Note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port.
 
 ## Installation
 
@@ -56,17 +66,29 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance
 
 DocumentDB Local accepts TLS connections on the gateway port and requires authentication. Connect with the username and password you set when starting the container, and because the container uses a self-signed certificate, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead).
 
+The code reads the same `DOCUMENTDB_USERNAME` and `DOCUMENTDB_PASSWORD` values exported during Docker setup and raises a clear error if either is missing.
+
 ```javascript
 const { MongoClient } = require('mongodb');
 
-const uri = 'mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true';
-const client = new MongoClient(uri);
+const username = process.env.DOCUMENTDB_USERNAME;
+const password = process.env.DOCUMENTDB_PASSWORD;
+if (!username || !password) {
+  throw new Error('Set DOCUMENTDB_USERNAME and DOCUMENTDB_PASSWORD before connecting');
+}
+
+const client = new MongoClient(
+  'mongodb://localhost:10260/?authSource=admin&tls=true&tlsAllowInvalidCertificates=true&directConnection=true',
+  {
+    auth: { username, password },
+  },
+);
 
 async function main() {
   await client.connect();
   const db = client.db('your_database');
   console.log('connected');
-  return db;
+  await client.close();
 }
 
 main().catch((error) => {
@@ -77,7 +99,8 @@ main().catch((error) => {
 
 ## Basic Operations
 
-The operations below all run inside `main()`, after `const db = client.db(...)` above.
+Replace the earlier `main()` function and its call with the example below. The
+operations all run inside `main()`, after `const db = client.db(...)`.
 `await` is only valid inside an `async` function, and `db` only exists in that scope —
 running these at the top level of a file gives `ReferenceError: db is not defined`.
 
@@ -113,7 +136,7 @@ main().catch((error) => {
 Aggregation pipelines, vector search, geospatial queries and change streams use the
 same syntax as the MongoDB shell. See the
 [Mongo Shell Quick Start](https://documentdb.io/docs/getting-started/mongo-shell-quickstart/)
-for worked examples, and the [API reference](https://documentdb.io/docs/api-reference/)
+for worked examples, and the [API reference](https://documentdb.io/docs/reference/)
 for the supported operator set.
 
 ## Next Steps