Skip to content

Update the release candidate guide for RC2 and disclose usage telemetry #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
guanzhousongmicrosoft wants to merge 2 commits into from
Closed

Update the release candidate guide for RC2 and disclose usage telemetry #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f4121b2
Point the release candidate page at RC2
guanzhousongmicrosoft Oct 9, 2026
bf1cdd8
Disclose the documentdb-local usage telemetry added in RC2
guanzhousongmicrosoft Oct 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion documentdb-local/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ The following table summarizes the available Docker commands for configuring the
| 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 run alphabetically using `mongosh`, once per fresh data volume. Syntax or runtime errors abort initialization. An attempted script run is not repeated on restart, so fix the scripts and use a fresh volume to retry. |
| Skip initialization with built-in sample data. | `--skip-init-data` | Overrides `SKIP_INIT_DATA` environment variable | `true`, `false` (`SKIP_INIT_DATA` only - the flag itself takes no value) | N/A | Legacy alias for `--init-data false`. Note that `SKIP_INIT_DATA=false` does the opposite of the flag: with `INIT_DATA` unset it enables the built-in sample data. 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 (takes no value) | N/A | Extended RUM is enabled by default. **Known issue:** this flag does not currently disable it - the container still starts with `documentdb_extended_rum` configured. |
| Enable telemetry data. | `--enable-telemetry [value]` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | **Known issue:** the value is validated at startup but no telemetry is currently emitted - the gateway's metrics and tracing exporters are disabled in this image, and an invalid value only serves to abort startup. |
| Enable telemetry data. | `--enable-telemetry [value]` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | The gateway's operational metrics, unrelated to [usage telemetry](#usage-telemetry). **Known issue:** the value is validated at startup but no telemetry is currently emitted - the gateway's metrics and tracing exporters are disabled in this image, and an invalid value only serves to abort startup. |
| Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | **Known issue:** the value is validated at startup but does not currently change what the container logs. To change the gateway's own verbosity, set the `DOCUMENTDB_LOG_LEVEL` environment variable instead; it takes a tracing filter such as `info` or `debug` (`quiet` is not one of its values). |

> `--skip-init-data` and `--disable-extended-rum` are the only options that take no value. Passing one anyway - for example `--disable-extended-rum false` - is rejected as an unexpected argument and the container exits.
Expand All @@ -134,6 +134,16 @@ docker run -dt \
--init-data true
```

## Usage telemetry

Starting with the 1.0 RC2 images (`pg15-1.0-rc2` to `pg18-1.0-rc2`), DocumentDB Local sends anonymous usage data by default. The 0.117 images used on this page send none, and neither do the native packages.

At startup and then hourly, the image reports its version, platform and CPU architecture to [Scarf](https://scarf.sh). It never sends database, collection or user names, queries, documents or credentials. A `[TELEMETRY]` notice in the container log says when it is on.

To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false`, `-e NO_ANALYTICS=1` or `-e DO_NOT_TRACK=1` before the image name, or `--disable-usage-telemetry` after it. In CI, turn it off explicitly: the image skips telemetry when `CI` is set inside the container, but `docker run` doesn't pass the host's `CI` through. `--enable-telemetry` is a separate setting for the gateway's own metrics and doesn't affect this.

The [privacy statement](https://github.com/documentdb/documentdb/blob/v1.0-RC2/documentdb-local/PRIVACY.md) has the details. The image also includes it at `/home/documentdb/PRIVACY.md`.

## Built-in sample data

Release 0.117 replaces the earlier small `sampledb` seed with the complete `StoreData` dataset. Loading remains opt-in: add `--init-data true` to the container arguments, as in the example above.
Expand Down
53 changes: 35 additions & 18 deletions getting-started/release-candidate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,53 @@
---
title: Try the 1.0 Release Candidate
description: Try DocumentDB 1.0 RC1 from release assets or container images. For testing only, with no upgrade path and no fixes to RC1. No date for 1.0 yet.
description: Try DocumentDB 1.0 RC2 from release assets or container images. For testing only, with no upgrade path and no fixes to RC2. No date for 1.0 yet.
---

# Try the 1.0 release candidate

[DocumentDB v1.0-RC1](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC1) is a preview of 1.0 for testing. Try your applications and workloads against it and [report what breaks](#report-issues) before 1.0 ships.
[DocumentDB v1.0-RC2](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2) is a preview of 1.0 for testing. Try your applications and workloads against it and [report what breaks](#report-issues) before 1.0 ships.

There is no date for 1.0 yet. A release candidate is meant to be close to what 1.0 ships, apart from fixes found during testing; 1.0 follows once the release candidates stop turning up blocking issues. The upgrade and support policy from 1.0 onward will be published with the final release.

> **For testing only.** Don't use a release candidate for production or for data you need to keep.
>
> - **No upgrade path.** Upgrades from 0.117 to an RC, between release candidates, and from an RC to 1.0 are not supported. Start from an empty instance or volume, and expect to discard it.
> - **No fixes to RC1.** Fixes go into the next release candidate or 1.0, not into RC1. Expect an RC2.
> - **No fixes to RC2.** Fixes go into the next release candidate or 1.0, not into RC2.
> - **Not the default.** GitHub marks the RC as a pre-release. The package repository, the container `latest` tag and GitHub's latest release stay on the current stable release, v0.117-0. You only get the RC by asking for it explicitly, as shown below.

## Changes since RC1

- **Usage telemetry in the container image.** The RC2 image sends anonymous usage data by default; native packages send nothing. See [Container image](#container-image).
- **Gateway v2 runtime.** The gateway now runs on its v2 runtime by default.
- **Init script errors stop startup.** RC1's known issue is fixed: an error in an `--init-data-path` script now stops the container with an error. The run isn't retried on restart, so fix the script and start from a new volume.
- **Permission fixes.** `find` and `aggregate` with `batchSize: 0` now check that the caller can read the collection, and `$merge` and `$out` now need insert or update permission on the target collection, not just read.

The [changelog](https://github.com/documentdb/documentdb/blob/v1.0-RC2/CHANGELOG.md) lists every change. There is no upgrade from RC1: if you tested RC1, start RC2 on a fresh host or a new volume.

## Container image

The RC images are tagged `pg15-1.0-rc1`, `pg16-1.0-rc1`, `pg17-1.0-rc1` and `pg18-1.0-rc1`, for Linux amd64 and arm64. Include the container's `Release Version` log line when you [report issues](#report-issues). Use a new volume, not one a 0.117 container has used:
The RC images are tagged `pg15-1.0-rc2`, `pg16-1.0-rc2`, `pg17-1.0-rc2` and `pg18-1.0-rc2`, for Linux amd64 and arm64. Include the container's `Release Version` log line when you [report issues](#report-issues). Use a new volume, not one a 0.117 or RC1 container has used:

```bash
docker run -dt -p 127.0.0.1:10260:10260 -v documentdb-rc1-data:/data --name docdb-rc1 \
docker run -dt -p 127.0.0.1:10260:10260 -v documentdb-rc2-data:/data --name docdb-rc2 \
-e USERNAME="${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
-e PASSWORD="${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0-rc1
ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0-rc2
```

Everything else in [DocumentDB Local](../documentdb-local/index.md) applies, with these differences:

- **Health check.** The first health check runs about 30 seconds after start. Wait until `docker inspect -f '{{.State.Health.Status}}' docdb-rc1` reports `healthy`.
- **A stale `postmaster.pid` refuses to start.** After `docker kill`, `docker rm -f` or a crash, the next container on that volume refuses to start; 0.117 removed the stale file automatically. Re-create the container once with `-e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true`, then without it. Run `docker stop` before `docker rm` to avoid this. As in 0.117, a second container on a volume that is already in use exits immediately.
- **Known issue: init script errors don't stop startup.** In RC1, an error in an `--init-data-path` script is logged but the container still reports success and marks the volume as initialized. Check `docker logs` after the first start; after fixing the script, start from a new volume. Fixed in the next release candidate.
- **Usage telemetry is on by default.** At startup and then hourly, the image reports its version, platform and CPU architecture to Scarf, and nothing about your data, queries or credentials. Turn it off with `-e DOCUMENTDB_USAGE_TELEMETRY=false`, `-e NO_ANALYTICS=1` or `-e DO_NOT_TRACK=1`, or pass `--disable-usage-telemetry` after the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry).
- **Health check.** The first health check runs about 30 seconds after start. Wait until `docker inspect -f '{{.State.Health.Status}}' docdb-rc2` reports `healthy`.
- **Stale `postmaster.pid`.** After `docker kill`, `docker rm -f` or a crash, the next start removes the stale file, as 0.117 did, but only when the volume's lock shows an RC2 container wrote it. Otherwise it refuses to start: re-create the container once with `-e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true`, then without it. Don't share a volume between hosts. As in 0.117, a second container on a volume that is already in use exits immediately.
- **PostgreSQL loss stops the container.** If PostgreSQL inside the container stops, the gateway fails requests straight away and the container exits after 20 seconds (`DOCUMENTDB_POSTMASTER_EXIT_TIMEOUT`).
- **`--disable-extended-rum` is ignored**, apart from a deprecation warning.
- **`--toast-compression lz4|pglz|default`** is new and defaults to `lz4`.

To remove the test instance and its data:

```bash
docker stop docdb-rc1 && docker rm docdb-rc1 && docker volume rm documentdb-rc1-data
docker stop docdb-rc2 && docker rm docdb-rc2 && docker volume rm documentdb-rc2-data
```

## Linux packages
Expand All @@ -46,14 +56,14 @@ The RC is not in the package repository. Use a clean, disposable Ubuntu 24.04 or

```sh
curl -fsSLo documentdb-install.sh https://documentdb.io/install.sh &&
sh documentdb-install.sh --version v1.0-RC1
sh documentdb-install.sh --version v1.0-RC2
```

It enables PGDG (plus EPEL and CRB on EL9), downloads this host's five RC1 packages from the [release](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC1), verifies them against its `SHA256SUMS` and runs the setup wizard. It doesn't add the DocumentDB package repository, so the host never picks up a stable release by accident. PostgreSQL 18 is the default; add `--pg-major 17` for 17, or `--dry-run` to see the plan first. Without `--version`, the same installer sets up v0.117-0.
It enables PGDG (plus EPEL and CRB on EL9), downloads this host's five RC2 packages from the [release](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2), verifies them against its `SHA256SUMS` and runs the setup wizard. It doesn't add the DocumentDB package repository, so the host never picks up a stable release by accident. PostgreSQL 18 is the default; add `--pg-major 17` for 17, or `--dry-run` to see the plan first. Without `--version`, the same installer sets up v0.117-0.

After an RC run, the installer refuses that host, even in stable mode. Use a fresh host for anything else.
After an RC run, the installer refuses that host, even in stable mode or for a later RC, so an RC1 host can't take RC2. Use a fresh host for anything else.

To check what you got, run `dpkg-query -W 'documentdb*' '*-documentdb'` or `rpm -qa '*documentdb*'`. RC1 packages are version `1.0~rc1`, `documentdb-gateway --version` prints `1.0.0-rc1`, and the extension version is `1.0-0`.
To check what you got, run `dpkg-query -W 'documentdb*' '*-documentdb'` or `rpm -qa '*documentdb*'`. RC2 packages are version `1.0~rc2`, `documentdb-gateway --version` prints `1.0.0-rc2`, and the extension version is `1.0-0`.

### Manual installation

Expand Down Expand Up @@ -89,8 +99,8 @@ sudo dnf -qy module disable postgresql
Download and verify the release files:

```bash
base=https://github.com/documentdb/documentdb/releases/download/v1.0-RC1
mkdir pkgs-rc1 && cd pkgs-rc1 &&
base=https://github.com/documentdb/documentdb/releases/download/v1.0-RC2
mkdir pkgs-rc2 && cd pkgs-rc2 &&
curl -fsSLO "$base/SHA256SUMS" &&
awk '{print $2}' SHA256SUMS | xargs -I{} curl -fsSLO "$base/{}" &&
sha256sum -c SHA256SUMS
Expand Down Expand Up @@ -131,13 +141,20 @@ To remove the RC, uninstall its packages and discard the host or its data direct

## Known issues

- **The setup admin can't create users with `readAnyDatabase` or `readWriteAnyDatabase`** ([#752](https://github.com/documentdb/documentdb/issues/752)). `createUser` with those roles fails with `User is not authorized to perform this action`. This also affects v0.117-0. On a package install, create the user on the host instead:
- **`distinct` or `count` on a grouped view can crash the server.** `distinct` on a view whose pipeline ends in `$group`, or `count` with a query on such a view, crashes the PostgreSQL backend. PostgreSQL restarts and disconnects every other session.
- **An expensive `$replaceAll` can outlive `maxTimeMS`.** A very costly `$replaceAll` on a large string can keep running after `maxTimeMS` expires and can't be cancelled.
- **`updateOne` can miss a match.** With a filter on a field other than `_id`, `updateOne` can report no match when PostgreSQL runs the statement with a generic plan. This is rare with default settings. Setting `plan_cache_mode = force_custom_plan` in the PostgreSQL configuration avoids it.
- **The setup admin can't create or drop users.** The admin user created at setup can't run `createUser` or `dropUser` over the MongoDB protocol. On a package install, manage users on the host instead:

```bash
sudo documentdb-gateway-admin create-user --username app --password-file app.pw \
--roles '[{"role":"readAnyDatabase","db":"admin"}]'
sudo documentdb-gateway-admin drop-user --username app
```

- **Container options.** `--log-level` and `--enable-telemetry` have no effect, and a `--data-path` that contains a space fails.
- **Collation is off by default.** `find`, `aggregate` and `count` with a `collation` fail as unsupported unless `documentdb_core.enableCollation` is on.

## Report issues

Open an issue in [documentdb/documentdb](https://github.com/documentdb/documentdb/issues) and include `v1.0-RC1`, your PostgreSQL major version, and either the package versions or the `Release Version` line from `docker logs docdb-rc1`, which names the build commit. The [release notes](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC1) list what changed since 0.117.
Open an issue in [documentdb/documentdb](https://github.com/documentdb/documentdb/issues) and include `v1.0-RC2`, your PostgreSQL major version, and either the package versions or the `Release Version` line from `docker logs docdb-rc2`, which names the build commit. The [release notes](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2) list what changed since 0.117.