1.0 release readiness

.github/workflows/continuous-integration.yml

@@ -5,10 +5,11 @@ on:
   push:
     branches:
       - main
-  # Runs on pull requests targeting the default branch
+  # Runs on pull requests targeting the default branch or the 1.0 release branch
   pull_request:
     branches:
       - main
+      - 1.0-release-readiness
 # Supersede in-flight runs for a pull request when new commits arrive, so a
 # rebase or force-push does not leave several runs racing on stale commits.
 # Pushes to main are never cancelled: every commit on the default branch
@@ -96,9 +97,9 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y createrepo-c dpkg-dev rpm python3
-      - name: Generate repository from v0.117-0
+      - name: Generate repository from v1.0-0
         env:
-          DOCUMENTDB_VERSION: v0.117-0
+          DOCUMENTDB_VERSION: v1.0-0
         run: .github/scripts/download_packages.sh
       - name: Verify release inventory and metadata
         run: python3 .github/scripts/verify_package_inventory.py

PACKAGE-INSTALL.md

@@ -2,9 +2,7 @@
 
 Repository-backed installation commands for DocumentDB.
 
-> This repository serves v0.117-0. v1.0-RC2 is for testing only, gets no fixes (those go into
-> a later RC or 1.0), has no upgrade path, and isn't in this repository; see
-> [Try the 1.0 release candidate](https://documentdb.io/docs/getting-started/release-candidate/).
+> This repository serves v1.0-0.
 
 ## Clean-host installer
 
@@ -15,14 +13,10 @@ curl -fsSLo documentdb-install.sh https://documentdb.io/install.sh &&
 sudo sh documentdb-install.sh
 ```
 
-This installs v0.117-0 from this repository on PostgreSQL 18; add `--pg-major 17`
-for 17. To try RC2, add `--version v1.0-RC2`. The installer then downloads this host's
-packages from the
-[v1.0-RC2 release](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2),
-verifies them against its `SHA256SUMS`, and doesn't use this repository. The
-`pgNN-1.0-rc2` container image also runs RC2; it sends anonymous usage telemetry by default
-(opt out with `-e DOCUMENTDB_USAGE_TELEMETRY=false`). See the
-[RC guide](https://documentdb.io/docs/getting-started/release-candidate/).
+This installs v1.0-0 from this repository on PostgreSQL 18; add `--pg-major 17`
+for 17. On a host where DocumentDB is already set up, it only reports that instance's status
+and doesn't upgrade it; to move an existing install to 1.0, see
+[Upgrading an existing install](#upgrading-an-existing-install).
 
 The site serves the `install.sh` attached to the release named in
 `scripts/publish-installer.mjs`, and the build fails if its SHA256 changes.
@@ -109,10 +103,12 @@ sudo apt install -y documentdb
 wall of GDAL candidate lines that never name the missing repository.
 
 ```bash
+if (. /etc/os-release && [ "$ID" = centos ]) && [ -f /etc/yum.repos.d/pgdg-redhat-all.repo ]; then sudo sed -i 's/rhel-\$releasever_major\.\$releasever_minor-/rhel-$releasever_major-/g' /etc/yum.repos.d/pgdg-redhat-all.repo; fi && \
 sudo dnf install -y dnf-plugins-core && \
 sudo dnf config-manager --set-enabled crb && \
 sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm && \
 sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-$(uname -m)/pgdg-redhat-repo-latest.noarch.rpm && \
+if (. /etc/os-release && [ "$ID" = centos ]) && [ -f /etc/yum.repos.d/pgdg-redhat-all.repo ]; then sudo sed -i 's/rhel-\$releasever_major\.\$releasever_minor-/rhel-$releasever_major-/g' /etc/yum.repos.d/pgdg-redhat-all.repo; fi && \
 sudo dnf -qy module disable postgresql && \
 sudo rpm --import https://documentdb.io/documentdb-archive-keyring.gpg && \
 printf '%s\n' \
@@ -229,7 +225,7 @@ Before using this anywhere but a private machine:
 
 ```bash
 sudo documentdb-setup --status      # gateway listener, service states, resolved paths
-documentdb-gateway --version        # DocumentDB version (0.117.0)
+documentdb-gateway --version        # DocumentDB version (1.0.0)
 dpkg -l | grep documentdb           # or: rpm -qa | grep documentdb
 ```
 
@@ -373,54 +369,89 @@ The current release publishes PostgreSQL 17 and 18. Install `documentdb-17` or
 
 ## Upgrading an existing install
 
-> **Warning:** In-place package upgrades from earlier releases are not supported yet. Use a
-> clean host or a new, empty PostgreSQL instance for the current fresh installation.
-> Removing packages alone does not create a fresh database: package removal preserves PostgreSQL data and
-> in-database content, and a later setup run reuses an initialized data directory. Upgrading only
-> `postgresql-N-documentdb` does not install the gateway, tools, common payload, or `documentdb-N`.
+Package installs from v0.116 or later upgrade in place to 1.0. Move the entire stack
+together; upgrading only `postgresql-N-documentdb` does not update the gateway, tools, common
+payload, or `documentdb-N`. These steps use systemd; upgrading a host without it isn't covered here.
+On a package-managed private PostgreSQL 18 instance:
 
-For a later point release that uses the same multi-package layout, move the entire stack
-together. On a package-managed private PostgreSQL 18 instance:
+> **Warning:** A host that ran a 1.0 release candidate (RC1 or RC2) has no upgrade path. Use a
+> clean host or a new, empty PostgreSQL instance.
+> Removing packages alone does not create a fresh database: package removal preserves PostgreSQL
+> data and in-database content, and a later setup run reuses an initialized data directory.
 
 ```bash
-sudo systemctl stop documentdb-gateway-local@18.service
-
 # Debian / Ubuntu
-sudo apt update
+sudo systemctl stop documentdb-gateway-local@18.service &&
+sudo apt update &&
 sudo apt install --only-upgrade documentdb-18 postgresql-18-documentdb \
   documentdb-common documentdb-gateway documentdb-postgresql-tools
 
 # EL9: use this instead of the apt commands above
+sudo systemctl stop documentdb-gateway-local@18.service &&
 sudo dnf upgrade documentdb-18 postgresql18-documentdb \
   documentdb-common documentdb-gateway documentdb-postgresql-tools
-
-# PostgreSQL has the old shared library loaded until it restarts.
-sudo systemctl restart documentdb-postgresql@18.service
 ```
 
-Then update the extensions in **every database** that has DocumentDB installed:
+Upgrading the packages does not update the database catalog. The simplest way is to restart
+PostgreSQL so it loads the new libraries, then re-run setup with the options you installed with.
+Setup updates the extensions and then starts the gateway:
 
-```sql
-ALTER EXTENSION documentdb_core UPDATE;
-ALTER EXTENSION documentdb UPDATE;
-ALTER EXTENSION documentdb_extended_rum UPDATE;  -- only if it is installed
+```bash
+sudo systemctl restart documentdb-postgresql@18.service &&
+sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin
 ```
 
-PostgreSQL applies available intermediate extension upgrade scripts automatically. Confirm
-afterwards with:
+Setup adds any missing `shared_preload_libraries` entries and updates the extensions, but only in
+the `postgres` database. If your gateway uses another database, take the manual route below. It also asks for the admin password and sets it on the existing admin
+user: enter the current password to keep it.
 
-```sql
-SELECT extname, extversion FROM pg_extension WHERE extname LIKE 'documentdb%';
+To update by hand, or for every other database that has DocumentDB installed, first check that
+the extended RUM library is preloaded:
+
+```bash
+sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d postgres -X -Atc "SHOW shared_preload_libraries;"
 ```
 
-Finally restart the gateway:
+If `pg_documentdb_extended_rum` is missing (possible on a 0.116 install), add it before updating;
+the update below would succeed without it, and index builds would fail later. If the gateway uses
+`postgres`, re-run setup as above. If it uses another database, add the library to
+`shared_preload_libraries` in the instance's `postgresql.conf` yourself: setup would point the
+gateway back at `postgres`. Then restart
+PostgreSQL, update the extensions in one transaction, and start the gateway only if that worked:
 
 ```bash
+sudo systemctl restart documentdb-postgresql@18.service &&
+sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d postgres \
+  -X -1 -v ON_ERROR_STOP=1 \
+  -c 'ALTER EXTENSION documentdb_core UPDATE;' \
+  -c 'ALTER EXTENSION documentdb UPDATE;' \
+  -c 'CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum CASCADE;' \
+  -c 'ALTER EXTENSION documentdb_extended_rum UPDATE;' &&
 sudo systemctl start documentdb-gateway-local@18.service
 ```
 
-Take a backup first. For an adopted PostgreSQL instance, restart its operator-managed
-PostgreSQL service instead of `documentdb-postgresql@18.service`.
+`-1` runs the statements as one transaction: if any fails, every extension stays at its old version
+and the gateway stays stopped. `-X` skips `~/.psqlrc`, which could otherwise turn `ON_ERROR_STOP` off. If DocumentDB is installed in other databases too, run the `psql` part for each of them, with
+that `-d`, before the last line, so the gateway starts only after every database is updated.
+PostgreSQL applies intermediate upgrade scripts automatically. Take a backup first.
+
+On a host with both PostgreSQL 17 and 18, `documentdb-common`, `documentdb-gateway` and
+`documentdb-postgresql-tools` serve both majors, so upgrading them affects both: stop both gateways
+(`documentdb-gateway-local@17.service` and `@18.service`) before upgrading, then update each major.
+
+For an adopted PostgreSQL instance, setup never restarts PostgreSQL. Stop the gateway
+(`documentdb-gateway-local@18.service`) before upgrading, restart the operator-managed PostgreSQL
+service yourself, then re-run
+`documentdb-setup --pg-version 18 --target-postgres-instance 18/main --admin-user admin` (with your cluster name); it
+updates the extensions and then starts the gateway. If
+setup has to change `shared_preload_libraries`, it exits without updating the extensions: restart
+PostgreSQL and run it once more. By hand, use that instance's own `psql` connection.
+
+Confirm afterwards with:
+
+```sql
+SELECT extname, extversion FROM pg_extension WHERE extname LIKE 'documentdb%';
+```
 
 ## Version pinning
 
@@ -449,17 +480,17 @@ published in the documentdb.io package repositories. Community builds are welcom
 For example, after checking out the matching release tag, build an extension package with:
 
 ```bash
-./packaging/build_packages.sh --os deb12 --pg 16
+./packaging/build_packages.sh --os deb12 --pg 16 --version 1.0.0
 ```
 
-That command builds only `postgresql-N-documentdb`. A custom full-stack package set uses
+`v1.0-0` and `v1.0-RC2` are on the same commit, so pass `--version`; without it the scripts can build RC-versioned packages. That command builds only `postgresql-N-documentdb`. A custom full-stack package set uses
 three entry points:
 
 - `packaging/build_packages.sh` — PostgreSQL extension
 - `packaging/gateway/build_gateway_packages.sh` — wire-protocol gateway
 - `packaging/build_extra_packages.sh` — tools, common payload, `documentdb-N`, and meta package
 
-The [v0.117 packaging guide](https://github.com/documentdb/documentdb/blob/v0.117-0/packaging/README.md)
+The [v1.0 packaging guide](https://github.com/documentdb/documentdb/blob/v1.0-0/packaging/README.md)
 documents their required arguments, version formats, prerequisites, and accepted targets.
 PostgreSQL 15 remains extension-only for package-managed installs because the setup tools
 require PostgreSQL 16 or newer.
@@ -474,9 +505,9 @@ they do not retain packages from older releases.
 Examples:
 
 ```text
-ubuntu24.04-documentdb_0.117.0_all.deb
-ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb
-rhel9-postgresql18-documentdb-0.117.0-1.el9.x86_64.rpm
+ubuntu24.04-documentdb_1.0.0_all.deb
+ubuntu24.04-postgresql-18-documentdb_1.0-0_amd64.deb
+rhel9-postgresql18-documentdb-1.0.0-1.el9.x86_64.rpm
 ```
 
 For a full stack, pass the five packages for the selected PostgreSQL major to one command:

app/ai/page.tsx

@@ -1,6 +1,7 @@
 import Image from "next/image";
 import Link from "next/link";
 import CommandSnippet from "../components/CommandSnippet";
+import TelemetryNote from "../components/TelemetryNote";
 import { getMetadata } from "../services/metadataService";
 import {
   documentdbGitHubForks,
@@ -27,29 +28,39 @@ export const metadata = getMetadata({
 });
 
 const quickRunCommand = `docker run -dt --name documentdb \\
-  -p 10260:10260 \\
-  ghcr.io/documentdb/documentdb/documentdb-local:latest \\
-  --username admin --password password`;
+  -p 127.0.0.1:10260:10260 \\
+  -e USERNAME=admin \\
+  -e PASSWORD=password \\
+  ghcr.io/documentdb/documentdb/documentdb-local:latest`;
 
 const connectCommand = `mongosh "mongodb://admin:password@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true"`;
 
-const createIndexCommand = `db.runCommand({
+const createIndexCommand = `// Real embeddings are longer: set dimensions to your model's size, such as 1536.
+db.documents.insertMany([
+  { title: "Vector indexes", category: "technical", embedding: [0.10, -0.02, 0.30] },
+  { title: "Release notes", category: "news", embedding: [0.90, 0.40, -0.10] }
+]);
+
+db.runCommand({
   createIndexes: "documents",
   indexes: [{
     key: { embedding: "cosmosSearch" },
     name: "vector_idx",
     cosmosSearchOptions: {
       kind: "vector-hnsw",
       similarity: "COS",
-      dimensions: 1536
+      dimensions: 3
     }
   }]
-});`;
+});
+
+// $vectorSearch filters need an index on each filtered field.
+db.documents.createIndex({ category: 1 });`;
 
 const vectorSearchCommand = `db.documents.aggregate([
   {
     $vectorSearch: {
-      queryVector: [0.12, -0.04, 0.31, /* ... 1536 dims */],
+      queryVector: [0.12, -0.04, 0.31],
       path: "embedding",
       limit: 10,
       numCandidates: 100,
@@ -113,7 +124,7 @@ const quickStartSteps = [
     step: "03",
     title: "Create a vector index",
     description:
-      "Create a native HNSW vector index with cosine similarity for embedding retrieval.",
+      "Add sample documents, a native HNSW vector index with cosine similarity, and an index on the field you filter by.",
     label: "Index",
     code: createIndexCommand,
   },
@@ -296,6 +307,7 @@ export default function AIPage() {
             </p>
             <div className="mt-5">
               <CommandSnippet command={quickRunCommand} label="Docker" />
+              <TelemetryNote />
             </div>
             <div className="mt-5 grid gap-3 sm:grid-cols-3">
               <div className="rounded-2xl border border-neutral-800 bg-neutral-900/70 p-4">
@@ -386,6 +398,7 @@ export default function AIPage() {
                 <p className="mt-2 text-sm leading-6 text-gray-400">{item.description}</p>
                 <div className="mt-5">
                   <CommandSnippet command={item.code} label={item.label} />
+                  {item.code === quickRunCommand && <TelemetryNote />}
                 </div>
               </article>
             ))}

app/components/AnnouncementBar.tsx

@@ -0,0 +1,19 @@
+import Link from "next/link";
+import { documentdbReleasePageUrl } from "../services/externalLinks";
+
+export default function AnnouncementBar() {
+  return (
+    <Link
+      href={documentdbReleasePageUrl}
+      className="block bg-gradient-to-r from-emerald-500/20 via-blue-500/20 to-emerald-500/20 px-4 py-2 text-center text-sm text-white transition-colors hover:from-emerald-500/30 hover:via-blue-500/30 hover:to-emerald-500/30"
+    >
+      <span className="mr-2 rounded-full bg-emerald-400/20 px-2 py-0.5 text-xs font-semibold uppercase tracking-[0.14em] text-emerald-200">
+        New
+      </span>
+      <span className="font-semibold">DocumentDB 1.0 is here.</span>{" "}
+      <span className="whitespace-nowrap text-emerald-200 underline-offset-4 hover:underline">
+        See what&apos;s new <span aria-hidden="true">&rarr;</span>
+      </span>
+    </Link>
+  );
+}

app/components/Markdown.tsx

@@ -8,6 +8,7 @@ import type { ReactElement } from 'react';
 import Code from './Code';
 import { headingAnchor } from '../lib/docsAnchors';
 import { resolveMarkdownLink } from '../lib/markdownLinks';
+import { withBasePath } from '../services/sitePath';
 
 interface MarkdownProps {
   content: string;
@@ -122,7 +123,7 @@ function getMarkdownComponents(sourcePath: string) {
     // Inline code
     code: ({ inline, children, ...props }: any) => {
       return (
-        <code className="bg-neutral-900/50 px-2 py-1 rounded text-green-400 font-mono text-sm" {...props}>
+        <code className="bg-neutral-900/50 px-2 py-1 rounded text-green-400 font-mono text-sm [overflow-wrap:anywhere]" {...props}>
           {children}
         </code>
       );
@@ -254,17 +255,16 @@ function getMarkdownComponents(sourcePath: string) {
 
     // Links: only external links open in a new tab; internal links (/docs/...,
     // /samples, #anchors) navigate in place
-    a: ({ children, href, ...props }: any) => {
+    a: ({ children, href, node: _node, ...props }: any) => {
       const resolvedHref = resolveMarkdownLink(href, sourcePath);
       const isExternal = /^https?:\/\//i.test(resolvedHref ?? '');
       const linkClassName = 'text-blue-400 hover:text-blue-300 transition-colors';
 
       // A rewritten href is a resolved document route, so it is known to be an
-      // internal page and is rendered with next/link. That applies the basePath
-      // from next.config identically on the server and in the browser -
-      // NEXT_BASE_PATH is not readable from the client bundle, so neither this
-      // component nor the resolver may prefix the path itself. Any other href
-      // is left exactly as the author wrote it.
+      // internal page and is rendered with next/link, which applies the
+      // basePath itself. Any other root-relative href may be a route Next does
+      // not own (/blogs/, /install.sh), so it stays a plain anchor and gets the
+      // base path from withBasePath.
       if (resolvedHref && resolvedHref !== href) {
         return (
           <Link href={resolvedHref} className={linkClassName} {...props}>
@@ -275,7 +275,7 @@ function getMarkdownComponents(sourcePath: string) {
 
       return (
         <a
-          href={resolvedHref}
+          href={resolvedHref && /^\/(?!\/)/.test(resolvedHref) ? withBasePath(resolvedHref) : resolvedHref}
           className={linkClassName}
           {...(isExternal ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
           {...props}

app/components/QuickStartTabs.tsx

@@ -3,6 +3,7 @@
 import Link from "next/link";
 import { useRef, useState } from "react";
 import CommandSnippet from "./CommandSnippet";
+import TelemetryNote from "./TelemetryNote";
 
 type QuickStartTabsProps = {
   dockerCommand: string;
@@ -109,6 +110,7 @@ export default function QuickStartTabs({
           Replace the username and password, then run the command.
         </p>
         <CommandSnippet command={dockerCommand} label="bash" />
+        <TelemetryNote />
         <p className="mt-4 text-sm leading-6 text-gray-300">
           Then connect with your preferred client.
         </p>