diff --git a/documentdb-local/index.md b/documentdb-local/index.md index b3c2896..7d5e661 100644 --- a/documentdb-local/index.md +++ b/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 "" 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,12 +182,13 @@ 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. @@ -174,7 +196,11 @@ Point it inside the data directory rather than at a volume of its own: the entry ### 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 diff --git a/getting-started/mongo-shell-quickstart.md b/getting-started/mongo-shell-quickstart.md index 046cc69..24dff2a 100644 --- a/getting-started/mongo-shell-quickstart.md +++ b/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 --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 `` and `` 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://:@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/). diff --git a/getting-started/nodejs-setup.md b/getting-started/nodejs-setup.md index 1a91fd5..f3f6b6f 100644 --- a/getting-started/nodejs-setup.md +++ b/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 --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 `` and `` 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://:@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 diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index bf9fd39..aff7103 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -57,19 +57,32 @@ For PostgreSQL 17, select `documentdb-17` and `rhel9-postgresql17-documentdb` in The `ubuntu24.04-` and `rhel9-` filename prefixes disambiguate release assets; they are not part of the package name. -### Extension only, from a single file +### Extension-only installation -If the host already has PostgreSQL and the PGDG extension dependencies (`postgresql-N-cron`, `-pgvector`, `-postgis-3`), the extension installs from one file — no gateway, no `documentdb-setup`: +If the host already has PostgreSQL and the PGDG extension dependencies (`postgresql-N-cron`, `-pgvector`, `-postgis-3`), install the extension payload together with the administrator tools. This does not install the stand-alone gateway or `documentdb-setup`: ```bash -sudo apt install ./ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb +sudo apt install ./ubuntu24.04-documentdb-postgresql-tools_0.117.0_all.deb \ + ./ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb ``` -In 0.117, `documentdb_extended_rum` is required by default on every supported PostgreSQL major. For extension-only setup, configure the PostgreSQL instance with `documentdb-tune`, restart it, and run both extension-creation statements it prints. `CREATE EXTENSION documentdb CASCADE` does not create `documentdb_extended_rum` automatically. +For PostgreSQL 17, use `ubuntu24.04-postgresql-17-documentdb_0.117-0_amd64.deb` instead. For arm64, replace `amd64` with `arm64` in the extension filename; the tools package is PostgreSQL- and architecture-independent. + +In 0.117, `documentdb_extended_rum` is required by default on every supported PostgreSQL major. For the default PostgreSQL 18 cluster on Ubuntu, configure it, restart it, and create both extensions in the `postgres` database: + +```bash +sudo documentdb-tune --pg-version 18 --cluster main --yes +sudo systemctl restart postgresql@18-main +sudo -u postgres /usr/bin/psql --cluster 18/main -d postgres -v ON_ERROR_STOP=1 \ + -c "CREATE EXTENSION IF NOT EXISTS documentdb CASCADE;" \ + -c "CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum CASCADE;" +``` + +Change `18` and `main` to the PostgreSQL major and cluster you are configuring. `documentdb-tune` prints the appropriate restart and connection commands for non-default instances. Both extension statements must run after the restart; `CREATE EXTENSION documentdb CASCADE` does not create `documentdb_extended_rum` automatically. See the [PostgreSQL package setup procedure](https://documentdb.io/docs/getting-started/packages/) for other instance layouts. ### Offline / air-gapped -Release assets alone are not enough — DocumentDB also needs PostgreSQL, `pg_cron`, `pgvector` and PostGIS from PGDG. Stage the full dependency closure on a connected machine of the **same distro, release and architecture**, serve it to the target as a local repository, then install with one command. Commands: [Offline / air-gapped install](https://documentdb.io/docs/getting-started/packages/#offline-air-gapped-install). +Release assets alone are not enough — DocumentDB also needs PostgreSQL, `pg_cron`, `pgvector` and PostGIS from PGDG. Stage the full dependency closure on a connected machine of the **same distro, release and architecture**, serve it to the target as a local repository, then install with one command. Commands: [Offline / air-gapped install](https://documentdb.io/docs/linux-packages/offline/). > Stage with `apt-cache depends --recurse` / `dnf download --alldeps`. `apt-get install --download-only` and a bare `dnf download --resolve` skip whatever is already installed on the staging machine; the bundle looks complete and the target dies with `Depends: adduser but it is not installable`. @@ -92,7 +105,7 @@ mongosh localhost:10260 -u admin -p '' --authenticationMechanism SCRAM Add `--load-sample-data` to the setup command to load the optional `StoreData` dataset. This requires `mongosh`; see [Built-in sample data](https://documentdb.io/docs/documentdb-local/#built-in-sample-data) for the collection contents. -> **Pre-GA:** In-place package upgrades from earlier releases are not supported yet. Use a clean host, or remove previous DocumentDB packages first. +> **Pre-GA:** In-place package upgrades from earlier releases are not supported yet. Use a clean host or a newly created PostgreSQL instance. Removing packages preserves the existing PostgreSQL data directory and does not turn that instance into a clean installation; do not reset or reuse an adopted instance as an upgrade workaround. ## What each release publishes @@ -122,12 +135,18 @@ Other targets — PostgreSQL 15/16, Debian 11/12/13, Ubuntu 22.04, and RHEL-comp ## Container image ```bash -docker run -dt -p 10260:10260 --name documentdb-container \ +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 documentdb-container \ ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \ - --username --password + --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \ + --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}" ``` -Credentials must be set at create time or authentication will not work. Port `10260` avoids clashing with a local MongoDB; if you prefer `27017`, change both the `-p` flag and your connection string. +The guards reject empty credentials so the container cannot fall through to its public defaults. The example binds only to the local host. To use host port `27017` while keeping the gateway on container port `10260`, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the internal gateway port too, add `--documentdb-port 27017`. `v0.117-0` publishes these multi-architecture tags (linux/amd64 and linux/arm64): diff --git a/getting-started/python-setup.md b/getting-started/python-setup.md index 2515211..d8b8b1b 100644 --- a/getting-started/python-setup.md +++ b/getting-started/python-setup.md @@ -37,29 +37,52 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py # 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 --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 `` and `` 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 Python examples 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 Python. > > **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. ## Connecting to DocumentDB 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. + 1. Basic Connection ```python + import os import pymongo - import sys - # Create a MongoDB client and open a connection to DocumentDB + username = os.environ.get('DOCUMENTDB_USERNAME') + password = os.environ.get('DOCUMENTDB_PASSWORD') + if not username or not password: + raise RuntimeError( + 'Set DOCUMENTDB_USERNAME and DOCUMENTDB_PASSWORD before connecting' + ) + client = pymongo.MongoClient( - 'mongodb://:@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true' + 'mongodb://localhost:10260/', + username=username, + password=password, + authSource='admin', + tls=True, + tlsAllowInvalidCertificates=True ) # Specify the database to be used @@ -69,11 +92,15 @@ DocumentDB Local accepts TLS connections on the gateway port and requires authen collection = db.sample_collection ``` -2. Connection with Authentication +2. Connection with certificate validation ```python - # With username and password client = pymongo.MongoClient( - 'mongodb://username:password@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true' + 'mongodb://localhost:10260/', + username=username, + password=password, + authSource='admin', + tls=True, + tlsCAFile='/path/to/documentdb-cert.pem' ) ``` @@ -81,7 +108,12 @@ DocumentDB Local accepts TLS connections on the gateway port and requires authen ```python # With additional options client = pymongo.MongoClient( - 'mongodb://:@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true', + 'mongodb://localhost:10260/', + username=username, + password=password, + authSource='admin', + tls=True, + tlsAllowInvalidCertificates=True, maxPoolSize=50, retryWrites=False, w='majority' @@ -232,7 +264,6 @@ DocumentDB Local accepts TLS connections on the gateway port and requires authen from pymongo.errors import ConnectionFailure try: - client = pymongo.MongoClient(connection_string) client.admin.command('ping') except ConnectionFailure as e: print(f"Connection error: {e}") @@ -254,7 +285,12 @@ DocumentDB Local accepts TLS connections on the gateway port and requires authen ```python # Configure connection pool client = pymongo.MongoClient( - connection_string, + 'mongodb://localhost:10260/', + username=username, + password=password, + authSource='admin', + tls=True, + tlsAllowInvalidCertificates=True, maxPoolSize=50, waitQueueTimeoutMS=2000 ) @@ -277,12 +313,26 @@ DocumentDB Local accepts TLS connections on the gateway port and requires authen ## Sample Application ```python +import os from flask import Flask, jsonify from pymongo import MongoClient -from datetime import datetime app = Flask(__name__) -client = MongoClient('mongodb://:@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true') +username = os.environ.get('DOCUMENTDB_USERNAME') +password = os.environ.get('DOCUMENTDB_PASSWORD') +if not username or not password: + raise RuntimeError( + 'Set DOCUMENTDB_USERNAME and DOCUMENTDB_PASSWORD before starting the app' + ) + +client = MongoClient( + 'mongodb://localhost:10260/', + username=username, + password=password, + authSource='admin', + tls=True, + tlsAllowInvalidCertificates=True +) db = client.sample_database @app.route('/users', methods=['GET']) diff --git a/getting-started/vscode-quickstart.md b/getting-started/vscode-quickstart.md index 100dffb..13bbdb4 100644 --- a/getting-started/vscode-quickstart.md +++ b/getting-started/vscode-quickstart.md @@ -31,8 +31,13 @@ Get started with DocumentDB using the Visual Studio Code extension for a seamles ```bash docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb - docker run -dt -p 10260:10260 --name documentdb-container documentdb --username --password - docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest || echo "No existing documentdb image to remove" + read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME + read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD + printf '\n' + export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD + 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 || echo "No existing documentdb image to remove" + fi ``` **PowerShell** @@ -40,15 +45,27 @@ Get started with DocumentDB using the Visual Studio Code extension for a seamles ```powershell docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb - docker run -dt -p 10260:10260 --name documentdb-container documentdb --username --password - docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest; if ($LASTEXITCODE -ne 0) { echo "No existing documentdb image to remove" } + $env:DOCUMENTDB_USERNAME = Read-Host 'DocumentDB username' + $securePassword = Read-Host 'DocumentDB password' -AsSecureString + $env:DOCUMENTDB_PASSWORD = [System.Net.NetworkCredential]::new('', $securePassword).Password + if ([string]::IsNullOrWhiteSpace($env:DOCUMENTDB_USERNAME) -or [string]::IsNullOrWhiteSpace($env:DOCUMENTDB_PASSWORD)) { + throw 'DocumentDB credentials cannot be empty' + } else { + docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb --username "$env:DOCUMENTDB_USERNAME" --password "$env:DOCUMENTDB_PASSWORD" + if ($LASTEXITCODE -eq 0) { + docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest + if ($LASTEXITCODE -ne 0) { echo "No existing documentdb image to remove" } + } + } ``` > **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 `` and `` with your own credentials. If you omit `--username`/`--password` the container falls back to the built-in `default_user` / `Admin100` — these are public, so anyone who can reach the published port can authenticate as admin. Always set your own. + > **Note:** Both versions prompt for credentials and reject empty values so the container cannot fall through to the public `default_user` / `Admin100` defaults. Enter the same values when the extension asks for the local connection credentials. + > + > **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 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. + > **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 enter `27017` in the extension. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port. 2. Connecting to your database - Locate and select the DocumentDB icon in the primary VS Code sidebar on the left-hand side.