Correct documentdb-local option reference against upstream source

documentdb-local/index.md

@@ -33,9 +33,27 @@ docker ps
 
 ```output
 CONTAINER ID   IMAGE                                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                                      NAMES
-5aff734a3591   ghcr.io/documentdb/documentdb/documentdb-local:latest                             "/bin/bash -c '/home…"   5 seconds ago   Up 4 seconds   0.0.0.0:10260->10260/tcp, :::10260->10260/tcp                                                              optimistic_blackwell
+5aff734a3591   ghcr.io/documentdb/documentdb/documentdb-local:latest                             "/bin/bash -c '/home…"   5 seconds ago   Up 4 seconds   0.0.0.0:10260->10260/tcp, :::10260->10260/tcp                                                              docdb
 ```
 
+> This container writes its data to `/data` inside the container. Nothing is mounted there in the command above, so the database is discarded when the container is removed. See `--data-path` in the table below to persist it.
+
+### Wait for the container to be ready
+
+`docker ps` reports the container as `Up` well before DocumentDB can accept connections - PostgreSQL has to initialize, the extensions have to be set up, and the admin user has to be created first. Connecting too early fails with `MongoServerSelectionError` or `ECONNREFUSED`.
+
+Wait for the ready banner in the logs before connecting:
+
+```bash
+docker logs -f docdb
+```
+
+```output
+=== DocumentDB is ready ===
+```
+
+First start typically takes a few tens of seconds.
+
 > The DocumentDB gateway endpoint is available on port `10260` by default. To access this with `mongosh`, run:
 
 ```bash
@@ -62,18 +80,23 @@ 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. |
-| Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | NA | Password for DocumentDB. This is required. |
-| The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `PORT` environment variable | INT | `10260` | The port needs to published - for example, using `-p 10260:10260`. |
-| Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | For example, to set `/usr/documentdb/data` as data directory, add this option to `docker run` command: `--mount type=bind,source=./.local/data,target=/usr/documentdb/data` |
+| 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`. |
+| 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 flag and the mount together: `--data-path /usr/documentdb/data` with `--mount type=bind,source=./.local/data,target=/usr/documentdb/data`. |
 | Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | Specify the owner for DocumentDB. |
-| Specify whether to start the PostgreSQL server. | `--start-pg` | NA | `true`, `false` | `true` | Specify whether to start the PostgreSQL server. |
-| Specify whether to create a user. | `--create-user` | NA | `true`, `false` | `true` | Specify whether to create a user. |
+| Specify whether to start the PostgreSQL server. | `--start-pg [value]` | Overrides `START_POSTGRESQL` environment variable | `true`, `false` | `true` | Specify whether to start the PostgreSQL server. |
+| Specify whether to create a user. | `--create-user [value]` | Overrides `CREATE_USER` environment variable | `true`, `false` | `true` | Specify whether to create a user. |
 | Specify the port for the PostgreSQL server. | `--pg-port [value]` | Overrides `POSTGRESQL_PORT` environment variable | INT | `9712` | Specify the port for the PostgreSQL server. |
-| Specify whether to allow external connections to PostgreSQL. | `--allow-external-connections` | Overrides `ALLOW_EXTERNAL_CONNECTIONS` environment variable | `true`, `false` | `false` | Specify whether to allow external connections to PostgreSQL. |
-| Specify the path to a certificate for securing traffic. | `--cert-path [value]` | Overrides `CERT_PATH` environment variable. | STRING | NA | You need to mount this file into the container. For example, to set `/mycert.pfx`, add this option to `docker run` command: `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`. Can set `CERT_SECRET` to the password for the certificate. |
-| Override default key with key in key file. | `--key-file [value]` | Overrides `KEY_FILE` environment variable. | STRING | NA | You need to mount this file into the container. For example, to set `/mykey.key`, add this option to `docker run` command: `--mount type=bind,source=./mykey.key,target=/mykey.key` |
-| Enable telemetry data. | `--enable-telemetry` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | Enable telemetry data sent to the usage collector (Azure Application Insights). |
-| Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | The verbosity of logs that will be emitted. |
+| Specify whether to allow external connections to PostgreSQL. | `--allow-external-connections [value]` | Overrides `ALLOW_EXTERNAL_CONNECTIONS` environment variable | `true`, `false` | `false` | Opens the container's internal PostgreSQL server to all interfaces. This does not affect the gateway, which always listens on all interfaces on the DocumentDB port. |
+| Specify the path to a certificate for securing traffic. | `--cert-path [value]` | Overrides `CERT_PATH` environment variable. | STRING | NA | PEM-format certificate. Must be set together with `--key-file` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mycert.pem`, add this option to `docker run` command: `--mount type=bind,source=./mycert.pem,target=/mycert.pem`. |
+| Override default key with key in key file. | `--key-file [value]` | Overrides `KEY_FILE` environment variable. | STRING | NA | PEM-format private key. Must be set together with `--cert-path` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mykey.key`, add this option to `docker run` command: `--mount type=bind,source=./mykey.key,target=/mykey.key` |
+| Set the TLS mode for client connections. | `--tlsMode [value]` | Overrides `TLS_MODE` environment variable | `disabled`, `allowTLS`, `requireTLS` | `allowTLS` | With `allowTLS` the gateway accepts both plain and TLS connections; `disabled` behaves the same way. `requireTLS` rejects plain connections, so every client must connect with `tls=true`. |
+| Enable initialization with built-in sample data. | `--init-data [value]` | Overrides `INIT_DATA` environment variable | `true`, `false` | `false` | Seeded once per data volume, on a fresh volume. Re-create the volume to seed again. |
+| Specify a directory of scripts for database initialization. | `--init-data-path [value]` | Overrides `INIT_DATA_PATH` environment variable | STRING | `/init_doc_db.d` | JavaScript files are executed in alphabetical order using `mongosh`, once per fresh data volume. Scripts should be idempotent - a failed run is not retried on restart. |
+| Skip initialization with built-in sample data. | `--skip-init-data` | Overrides `SKIP_INIT_DATA` environment variable | N/A | N/A | Legacy alias for `--init-data false`. Does not affect `--init-data-path`. |
+| Disable the use of extended RUM for indexes. | `--disable-extended-rum` | Overrides `DISABLE_EXTENDED_RUM` environment variable | N/A | `false` | Extended RUM is enabled by default. |
+| Enable telemetry data. | `--enable-telemetry [value]` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | Enable telemetry data sent to the usage collector. |
+| Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | The verbosity of logs that will be emitted. To set the gateway's own log level, use the `DOCUMENTDB_LOG_LEVEL` environment variable. |
 
 
 ## Feature support
@@ -83,15 +106,29 @@ Please refer to the [documentdb](https://documentdb.io/docs/) documentation for
 
 ## Installing certificates 
 
-By default, DocumentDB Local generates new self-signed certificates each time the container starts. To prevent certificate errors, install them on your local machine. The example below shows how to use this setup with `mongosh`.
+If you do not supply your own certificate with `--cert-path` and `--key-file`, DocumentDB Local generates a self-signed certificate on first start and reuses it on subsequent starts, so the certificate stays stable across restarts. To prevent certificate errors, install it on your local machine. The example below shows how to use this setup with `mongosh`.
 
 ### Get certificate
 
+The gateway chooses where to store auto-generated TLS material based on which directories are writable, so pin the location with `DOCUMENTDB_TLS_STATE_DIR` when starting the container:
+
+```bash
+docker run -dt -p 10260:10260 --name docdb \
+  -e DOCUMENTDB_TLS_STATE_DIR=/data/tls \
+  ghcr.io/documentdb/documentdb/documentdb-local:latest --username demo --password test
+```
+
 In a `bash` window, run the following to copy the certificate from the container to the local
 host: 
 
 ```bash
-docker cp docdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem
+docker cp docdb:/data/tls/cert.pem ~/documentdb-cert.pem
+```
+
+If you did not set `DOCUMENTDB_TLS_STATE_DIR`, the gateway logs the path it chose on startup:
+
+```bash
+docker logs docdb | grep "TLS auto-gen"
 ```
 
 ### Use the certificate with mongosh
@@ -102,7 +139,7 @@ mongosh localhost:10260 -u demo -p test --authenticationMechanism SCRAM-SHA-256
 
 ```output
 Current Mongosh Log ID:	690ce1171181053c6edbf354
-Connecting to:		mongodb://<credentials>@localhost:10260/?directConnection=true&serverSelectionTimeoutMS=2000&authMechanism=SCRAM-SHA-256&tls=true&tlsCAFile=%2FUsers%2Fgeeichbe%2Fdocumentdb-cert.pem&appName=mongosh+2.5.1
+Connecting to:		mongodb://<credentials>@localhost:10260/?directConnection=true&serverSelectionTimeoutMS=2000&authMechanism=SCRAM-SHA-256&tls=true&tlsCAFile=%2Fhome%2Fuser%2Fdocumentdb-cert.pem&appName=mongosh+2.5.1
 Using MongoDB:		7.0.0
 Using Mongosh:		2.5.1
 mongosh 2.5.9 is available for download: https://www.mongodb.com/try/download/shell

getting-started/mongo-shell-quickstart.md

@@ -40,7 +40,7 @@ docker ps
 
 ## Connecting to DocumentDB
 
-DocumentDB Local terminates TLS on the gateway port. The container generates a new self-signed certificate on each start, so the simplest local connection skips certificate validation with `tlsAllowInvalidCertificates=true`.
+DocumentDB Local terminates TLS on the gateway port. 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"

getting-started/nodejs-setup.md

@@ -52,7 +52,7 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance
 
 ## Connecting to DocumentDB
 
-DocumentDB Local requires TLS and authentication on the gateway port. Connect with the username and password you set when starting the container, and because the container generates a new self-signed certificate on each start, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead).
+DocumentDB Local requires TLS and authentication on the gateway port. 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).
 
 ```javascript
 const { MongoClient } = require('mongodb');

getting-started/python-setup.md

@@ -48,7 +48,7 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py
 
 ## Connecting to DocumentDB
 
-DocumentDB Local requires TLS and authentication on the gateway port. Connect with the username and password you set when starting the container, and because the container generates a new self-signed certificate on each start, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead).
+DocumentDB Local requires TLS and authentication on the gateway port. 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).
 
 1. Basic Connection
    ```python