diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 89f18f0..b3a88f3 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.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 diff --git a/PACKAGE-INSTALL.md b/PACKAGE-INSTALL.md index 98b631a..799720f 100644 --- a/PACKAGE-INSTALL.md +++ b/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: diff --git a/app/ai/page.tsx b/app/ai/page.tsx index b4e792a..ca46784 100644 --- a/app/ai/page.tsx +++ b/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,13 +28,20 @@ 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" }, @@ -41,15 +49,18 @@ const createIndexCommand = `db.runCommand({ 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() {

+
@@ -386,6 +398,7 @@ export default function AIPage() {

{item.description}

+ {item.code === quickRunCommand && }
))} diff --git a/app/components/AnnouncementBar.tsx b/app/components/AnnouncementBar.tsx new file mode 100644 index 0000000..a60c803 --- /dev/null +++ b/app/components/AnnouncementBar.tsx @@ -0,0 +1,19 @@ +import Link from "next/link"; +import { documentdbReleasePageUrl } from "../services/externalLinks"; + +export default function AnnouncementBar() { + return ( + + + New + + DocumentDB 1.0 is here.{" "} + + See what's new + + + ); +} diff --git a/app/components/Markdown.tsx b/app/components/Markdown.tsx index 8ab9d00..ae555f2 100644 --- a/app/components/Markdown.tsx +++ b/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 ( - + {children} ); @@ -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 ( @@ -275,7 +275,7 @@ function getMarkdownComponents(sourcePath: string) { return ( +

Then connect with your preferred client.

diff --git a/app/components/TelemetryNote.tsx b/app/components/TelemetryNote.tsx new file mode 100644 index 0000000..fcbe371 --- /dev/null +++ b/app/components/TelemetryNote.tsx @@ -0,0 +1,18 @@ +import Link from "next/link"; +import { documentdbLocalPrivacyUrl } from "../services/externalLinks"; + +const linkClass = "text-blue-300 underline decoration-blue-300/40 underline-offset-4 hover:text-blue-200"; + +// The documentdb-local image reports usage by default from 1.0, so every Docker start command shows the opt-out. +export default function TelemetryNote() { + return ( +

+ The image sends usage telemetry by default. Add{" "} + -e DOCUMENTDB_USAGE_TELEMETRY=false before the image name to + turn it off.{" "} + What is sent + {" · "} + Privacy statement +

+ ); +} diff --git a/app/docs/[section]/[[...slug]]/page.tsx b/app/docs/[section]/[[...slug]]/page.tsx index 1662ba0..09edbcd 100644 --- a/app/docs/[section]/[[...slug]]/page.tsx +++ b/app/docs/[section]/[[...slug]]/page.tsx @@ -5,15 +5,16 @@ import { getAllArticlePaths, getArticleByPath } from "../../../services/articleS import { getMetadata } from "../../../services/metadataService"; import ComingSoon from "../../../components/ComingSoon"; import CommandSnippet from "../../../components/CommandSnippet"; +import TelemetryNote from "../../../components/TelemetryNote"; import Markdown from "../../../components/Markdown"; import MovedNotice from "../../../components/MovedNotice"; import { aptTargetLabels } from "../../../lib/packageInstall"; const dockerQuickRunCommand = `docker run -dt --name documentdb \\ -p 127.0.0.1:10260:10260 \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username '' \\ - --password ''`; + -e USERNAME='' \\ + -e PASSWORD='' \\ + ghcr.io/documentdb/documentdb/documentdb-local:latest`; const primerPrimaryLinkClass = "inline-flex w-full items-center justify-center rounded-md bg-blue-500 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-blue-400 sm:w-auto"; @@ -276,6 +277,7 @@ export default async function ArticlePage({ params }: PageProps) {

+

Wait for the readiness banner in{" "} @@ -299,10 +301,6 @@ export default async function ArticlePage({ params }: PageProps) { PostgreSQL, topology, services, and configuration. Install with apt or dnf on {aptTargetLabels.ubuntu24} or EL9, then run the setup wizard.

-

- Pre-GA, fresh installation only; in-place upgrades from earlier - releases are not supported. -

- Operator preview + Generally available · Operator 1.0.0

DocumentDB Kubernetes Operator @@ -345,12 +345,12 @@ export default function KubernetesOperatorPage() {

- Preview status + Versions

- The operator is still in preview. Use this page to assess fit, - then follow the quick start or multi-cluster guides for the - current support envelope. + The operator has its own version numbers. Choose a release + compatible with your engine and Kubernetes versions, then + follow the quick start or multi-cluster guides.

@@ -457,7 +457,7 @@ export default function KubernetesOperatorPage() { What to expect before you start

- The operator preview targets Kubernetes 1.35+, requires + The operator targets Kubernetes 1.35+, requires cert-manager to be installed first, and uses CloudNativePG under the hood. Cross-cluster topologies also require network connectivity between clusters and the documented multi-cluster diff --git a/app/layout.tsx b/app/layout.tsx index b13b0c4..fd20d41 100644 --- a/app/layout.tsx +++ b/app/layout.tsx @@ -1,6 +1,7 @@ import type { Metadata } from "next"; import { Inter } from "next/font/google"; import "./globals.css"; +import AnnouncementBar from "./components/AnnouncementBar"; import Navbar from "./components/Navbar"; import { getMetadata } from "./services/metadataService"; @@ -19,6 +20,7 @@ export default function RootLayout({ return ( + {children}

diff --git a/app/lib/packageInstall.ts b/app/lib/packageInstall.ts index dec7612..4cfaafb 100644 --- a/app/lib/packageInstall.ts +++ b/app/lib/packageInstall.ts @@ -106,8 +106,18 @@ sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-${ sudo dnf config-manager --set-enabled crb && \\ sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-${rhelMajorVersion}.noarch.rpm`; - return `${distributionPrerequisites} && \\ -sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-${rhelMajorVersion}-${arch}/pgdg-redhat-repo-latest.noarch.rpm && \\ + // CentOS Stream has no minor release, so PGDG's rhel-$major.$minor path 404s; install.sh does the same. + // It runs first too, so a repo file left by an earlier attempt can't fail the first dnf call. + const pgdgCentosStreamFix = + rpmTarget === "rhel9" + ? "" + : `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 && \\`; + + const beforePgdg = pgdgCentosStreamFix && `${pgdgCentosStreamFix}\n`; + const afterPgdg = pgdgCentosStreamFix && `\n${pgdgCentosStreamFix}`; + + return `${beforePgdg}${distributionPrerequisites} && \\ +sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-${rhelMajorVersion}-${arch}/pgdg-redhat-repo-latest.noarch.rpm && \\${afterPgdg} sudo dnf -qy module disable postgresql && \\ sudo rpm --import https://documentdb.io/documentdb-archive-keyring.gpg && \\ printf '%s\\n' \\ diff --git a/app/lib/releaseInfo.ts b/app/lib/releaseInfo.ts index 2b5ac11..52e45f6 100644 --- a/app/lib/releaseInfo.ts +++ b/app/lib/releaseInfo.ts @@ -36,12 +36,12 @@ export type ReleaseInfo = { // A reference release, not evidence of current repository availability. export const FALLBACK_RELEASE: ReleaseInfo = { - tagName: "v0.117-0", - aptVersion: "0.117-0", - rpmVersion: "0.117.0-1.el9", - metaVersion: "0.117.0", - metaRpmVersion: "0.117.0-1", - releaseUrl: "https://github.com/documentdb/documentdb/releases/tag/v0.117-0", + tagName: "v1.0-0", + aptVersion: "1.0-0", + rpmVersion: "1.0.0-1.el9", + metaVersion: "1.0.0", + metaRpmVersion: "1.0.0-1", + releaseUrl: "https://github.com/documentdb/documentdb/releases/tag/v1.0-0", assetNames: [], }; diff --git a/app/packages/layout.tsx b/app/packages/layout.tsx index c81a967..29b4677 100644 --- a/app/packages/layout.tsx +++ b/app/packages/layout.tsx @@ -4,7 +4,7 @@ import { getMetadata } from "../services/metadataService"; export const metadata = getMetadata({ title: "Install DocumentDB - Docker and Linux Packages", description: - "Run DocumentDB with Docker on Linux, macOS, or Windows, or install Linux packages on Ubuntu 24.04 or RHEL/Rocky 9 with apt or dnf. Linux packages are pre-GA and for fresh installs.", + "Run DocumentDB with Docker on Linux, macOS, or Windows, or install Linux packages on Ubuntu 24.04 or RHEL/Rocky 9 with apt or dnf.", path: "/packages/", extraKeywords: ["install", "Linux", "APT", "RPM", "dnf", "Ubuntu", "RHEL", "Rocky Linux", "Docker"], }); diff --git a/app/packages/page.tsx b/app/packages/page.tsx index ceb6497..273df14 100644 --- a/app/packages/page.tsx +++ b/app/packages/page.tsx @@ -4,6 +4,7 @@ import Link from "next/link"; import { useSearchParams } from "next/navigation"; import { Suspense, useEffect, useState } from "react"; import CommandSnippet from "../components/CommandSnippet"; +import TelemetryNote from "../components/TelemetryNote"; import { aptTargetLabels, aptTargetPgVersions, @@ -29,9 +30,9 @@ import { const dockerCommand = `docker run -dt --name documentdb \\ -p 127.0.0.1:10260:10260 \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username '' \\ - --password ''`; + -e USERNAME='' \\ + -e PASSWORD='' \\ + ghcr.io/documentdb/documentdb/documentdb-local:latest`; const nextGuides = [ { title: "VS Code", href: "/docs/getting-started/vscode-quickstart" }, @@ -206,8 +207,9 @@ export default function PackagesPage() {
-

- Pre-GA: fresh installs only. In-place upgrades from earlier releases are not supported. +

+ Already running DocumentDB from packages?{" "} + Upgrade in place instead.

{releaseStatus === "loading" ? (

Checking the published package release...

@@ -314,6 +316,7 @@ export default function PackagesPage() {

1. Start DocumentDB

With Docker running, replace the username and password, then run:

{selectionReady && } + {selectionReady && }

It takes a few seconds to accept connections. Volumes, image versions, and readiness checks are in the{" "} Docker quickstart. diff --git a/app/page.tsx b/app/page.tsx index f014430..e522afa 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -3,6 +3,7 @@ import Link from "next/link"; import QuickStartTabs from "./components/QuickStartTabs"; import { documentdbKubernetesOperatorQuickStartUrl, + documentdbReleasePageUrl, documentdbVsCodeLocalQuickStartDeepLink, } from "./services/externalLinks"; import { getMetadata } from "./services/metadataService"; @@ -38,9 +39,9 @@ type Capability = { const quickRunCommand = `docker run -dt --name documentdb \\ -p 127.0.0.1:10260:10260 \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username '' \\ - --password ''`; + -e USERNAME='' \\ + -e PASSWORD='' \\ + ghcr.io/documentdb/documentdb/documentdb-local:latest`; const kubernetesOperatorEntryPoints = [ { @@ -117,12 +118,37 @@ const capabilities: Capability[] = [ ]; const trustBadges = [ + "1.0 with planned long-term support", "Built on PostgreSQL", "Native BSON", "MIT licensed", "Runs locally with Docker", ]; +const releaseHighlights = [ + { + eyebrow: "Versioning", + title: "Long-term support or development?", + description: + "How the proposed 1.0 LTS track and the development track differ, and which one fits your team.", + href: "/blogs/posts/versioning/", + }, + { + eyebrow: "Tools", + title: "DocumentDB extension for Visual Studio Code 1.0", + description: + "Start DocumentDB Local in a few clicks, bring your data, and understand it with Query Insights.", + href: "/blogs/posts/documentdb-for-vs-code-1-0/", + }, + { + eyebrow: "Kubernetes", + title: "DocumentDB 1.0 on Kubernetes", + description: + "Operator 1.0.0 is generally available. Deploy and manage DocumentDB clusters declaratively.", + href: "/blogs/posts/kubernetes-operator-versioning/", + }, +]; + const credibilityPoints = [ { value: documentdbGitHubStars, @@ -313,7 +339,7 @@ export default function Home() { DocumentDB

- A powerful, scalable, fully MongoDB compatible open-source database built for modern applications + A powerful, scalable, MongoDB-compatible open-source database built for modern applications

Open source and MIT licensed, with native BSON, advanced @@ -386,6 +412,50 @@ export default function Home() {

+
+
+
+
+

+ DocumentDB 1.0 +

+

+ What's new in 1.0 +

+
+ + Explore DocumentDB 1.0 + +
+ +
+ {releaseHighlights.map((item) => ( + +

+ {item.eyebrow} +

+

+ {item.title} +

+

+ {item.description} +

+ + Read post + + + ))} +
+
+
+
@@ -480,7 +550,7 @@ export default function Home() {

- Operator preview + Kubernetes operator

DocumentDB Kubernetes Operator @@ -511,11 +581,11 @@ export default function Home() {

- Preview with local, hybrid, and multi-cluster paths + Local, hybrid, and multi-cluster paths

- The operator is still in preview. Start with the overview, then - follow the quick start or multi-cluster guides. + Start with the overview, then follow the quick start or + multi-cluster guides.

diff --git a/app/services/articleService.ts b/app/services/articleService.ts index 0b0007d..7f0d15e 100644 --- a/app/services/articleService.ts +++ b/app/services/articleService.ts @@ -30,6 +30,10 @@ const virtualSections: Record [!NOTE] +> The DocumentDB Local image sends usage telemetry by default. To turn it off, add \`-e DOCUMENTDB_USAGE_TELEMETRY=false\` before the image name. See [Usage telemetry](/docs/documentdb-local#usage-telemetry) and the [privacy statement](https://github.com/documentdb/documentdb/blob/v1.0-0/documentdb-local/PRIVACY.md).`; + const dockerGuideContent = `# Docker Quick Start Run DocumentDB locally with Docker and verify the setup before moving to driver code. For installation choices, open [Docker installation](/packages?method=docker) or [Linux packages installation](/packages?method=packages). @@ -53,12 +57,14 @@ Then start the container: \`\`\`bash docker run -dt --name documentdb \\ -p 127.0.0.1:10260:10260 \\ + -e USERNAME='' \\ + -e PASSWORD='' \\ ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username '' \\ - --password '' \\ --init-data true \`\`\` +${documentdbLocalTelemetryNote} + > Replace \`\` and \`\` with your own credentials. > > \`-p 127.0.0.1:10260:10260\` keeps the endpoint on loopback. A bare \`-p 10260:10260\` @@ -97,7 +103,7 @@ The certificate bypass below is for **local development only**. Use a trusted ce \`\`\`bash mongosh localhost:10260 \\ -u '' \\ - -p '' \\ + -p \\ --authenticationMechanism SCRAM-SHA-256 \\ --tls \\ --tlsAllowInvalidCertificates @@ -155,6 +161,11 @@ Until you remove it, re-running \`docker run --name documentdb\` fails with \`Conflict. The container name "/documentdb" is already in use\`. Mount a named volume (\`-v documentdb-data:/data\`) before storing anything you want to keep. +A newer image on an existing data volume does not update the DocumentDB schema in that +volume ([documentdb#773](https://github.com/documentdb/documentdb/issues/773)). To move data +from an earlier release or a 1.0 release candidate to 1.0, start the 1.0 image on a new +volume and reload your data, for example with \`mongodump\` and \`mongorestore\`. + ## Troubleshooting and debugging If something does not work as expected: @@ -185,13 +196,10 @@ The current official release publishes the full stack — extension, gateway, se **Recommended:** install the complete stack, then create a new private PostgreSQL 18 instance. The commands detect architecture on the Linux host where you run them. For containers or macOS/Windows evaluation, choose [Docker installation](/packages?method=docker). > [!IMPORTANT] -> This pre-GA release supports **fresh installation only**, not in-place package upgrades from earlier releases. Use a clean host or a new, empty PostgreSQL instance. Removing packages preserves database files; reinstalling is not a data reset. +> Already running v0.116 or v0.117 from packages? Follow [Upgrading](/docs/linux-packages#upgrading) instead of installing again. Hosts that ran a 1.0 release candidate have no upgrade path; use a clean host. Removing packages preserves database files; reinstalling is not a data reset. > [!NOTE] -> Need another distribution or PostgreSQL major? We welcome community builds. Check out the matching release tag and use the version-parameterized [packaging scripts](https://github.com/documentdb/documentdb/blob/v0.117-0/packaging/README.md). \`build_packages.sh\` builds the extension, \`gateway/build_gateway_packages.sh\` builds the gateway, and \`build_extra_packages.sh\` builds the common, tools, stand-alone, and meta packages. PostgreSQL 15 is extension-only because the setup tools require PostgreSQL 16 or newer. These builds are on demand and are not official release assets hosted by documentdb.io. - -> [!NOTE] -> Want to try DocumentDB 1.0? [v1.0-RC2](/docs/getting-started/release-candidate) is for testing only, gets no fixes (those go into a later RC or 1.0) and has no upgrade path. It isn't in the package repository, so the commands below install v0.117-0. +> Need another distribution or PostgreSQL major? We welcome community builds. Check out the matching release tag, pass \`--version 1.0.0\` (an RC tag shares the 1.0 commit), and use the version-parameterized [packaging scripts](https://github.com/documentdb/documentdb/blob/v1.0-0/packaging/README.md). \`build_packages.sh\` builds the extension, \`gateway/build_gateway_packages.sh\` builds the gateway, and \`build_extra_packages.sh\` builds the common, tools, stand-alone, and meta packages. PostgreSQL 15 is extension-only because the setup tools require PostgreSQL 16 or newer. These builds are on demand and are not official release assets hosted by documentdb.io. You do not need PostgreSQL already installed — the setup wizard creates and manages its own instance. The install does add the PGDG repository and pull PostgreSQL, PostGIS and around 160 packages (about 140 MB), so pick a host you are willing to have PGDG on. @@ -204,11 +212,8 @@ curl -fsSLo documentdb-install.sh https://documentdb.io/install.sh && sudo sh documentdb-install.sh \`\`\` -This installs v0.117-0 from the package repository on PostgreSQL 18; add \`--pg-major 17\` for 17. -To try RC2, run \`sudo sh documentdb-install.sh --version v1.0-RC2\` instead. -It 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 the package 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](/docs/getting-started/release-candidate). -RC2 gets no fixes and has no upgrade path, so use a clean host. +This installs the current release (v1.0-0) from the package repository on PostgreSQL 18; add \`--pg-major 17\` for 17. +On a host where DocumentDB is already set up, the installer only reports its status and doesn't upgrade it; to move an existing install to 1.0, follow [Upgrading](/docs/linux-packages#upgrading). ## Install @@ -412,7 +417,7 @@ Use the extension package for your PostgreSQL major: \`postgresql-N-documentdb\` or \`postgresqlN-documentdb\` on EL9. You own PostgreSQL configuration, extension activation, and service restarts. Create \`documentdb_extended_rum\` as well as \`documentdb\`: \`CREATE EXTENSION documentdb CASCADE\` does not pull it in, and without it every index -creation fails. Follow the matching release's [manual package instructions](https://github.com/documentdb/documentdb/blob/v0.117-0/packaging/README.md), +creation fails. Follow the matching release's [manual package instructions](https://github.com/documentdb/documentdb/blob/v1.0-0/packaging/README.md), or the [extension-only offline instructions](/docs/linux-packages/offline#smaller-offline-cases) when PostgreSQL and all extension dependencies are already installed. @@ -433,51 +438,85 @@ For an adopted instance, use the operator's existing PostgreSQL connection inste ## Upgrading -> [!WARNING] -> In-place package upgrades from earlier releases are not supported yet. Use a clean host -> or a new, empty PostgreSQL instance and follow the current -> [fresh installation](/docs/getting-started/packages). 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. Move it to a +> clean host or a new, empty PostgreSQL instance and follow the +> [fresh installation](/docs/getting-started/packages). 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 +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: + +\`\`\`bash +sudo systemctl restart documentdb-postgresql@18.service && +sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin \`\`\` -Then update the extensions in **every database** that has DocumentDB installed: +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 -ALTER EXTENSION documentdb_core UPDATE; -ALTER EXTENSION documentdb UPDATE; -ALTER EXTENSION documentdb_extended_rum UPDATE; -- only if installed +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 \`\`\` -PostgreSQL applies intermediate upgrade scripts automatically. 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. ## Remove or reset @@ -662,7 +701,7 @@ Then continue with [Set up and connect](/docs/getting-started/packages#set-up-an If the target already has PostgreSQL, the PGDG extension dependencies (\`postgresql-N-cron\`, \`-pgvector\`, \`-postgis-3\`) and \`jq\`, you do not need a bundle: -- **Extension only, one file** — \`sudo apt install ./ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb\`. No gateway and no \`documentdb-setup\`. +- **Extension only, one file** — \`sudo apt install ./ubuntu24.04-postgresql-18-documentdb_1.0-0_amd64.deb\`. No gateway and no \`documentdb-setup\`. - **Full stack from the release assets** — pass the five packages for the selected PostgreSQL major to a *single* \`apt install\` / \`dnf install\`: \`documentdb-N\`, the matching \`postgresql-N-documentdb\` / \`postgresqlN-documentdb\` extension, \`documentdb-common\`, \`documentdb-gateway\`, and \`documentdb-postgresql-tools\`. For PostgreSQL 18 only, the optional \`documentdb\` meta package may be included; it selects \`documentdb-18\`. Local files resolve dependencies only against enabled repositories, so a package whose dependencies are not included still fails. `; @@ -694,7 +733,7 @@ const optionalSampleDataContent = `Sample data is **opt-in**, not required for y const vscodeQuickStartGuideContent = `# Visual Studio Code Quick Start -Use DocumentDB for VS Code to set up a local DocumentDB instance, browse sample data, and create your first database without leaving the editor. +Use the DocumentDB extension for Visual Studio Code to set up a local DocumentDB instance, browse sample data, and create your first database without leaving the editor. The extension can create the instance for you: it pulls the official image, creates a container and persistent data volume, generates credentials, waits until the database accepts connections, and saves the connection. It does not install Docker. @@ -703,7 +742,7 @@ Already running DocumentDB? Skip provisioning and [connect your existing instanc ## Prerequisites - [Visual Studio Code](https://code.visualstudio.com/) -- The [DocumentDB for VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb) +- The [DocumentDB extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb) - Docker Desktop or Docker Engine, set to Linux containers, running wherever VS Code is - Optional: [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/) for independent connection checks @@ -745,11 +784,13 @@ Start it with Docker: \`\`\`bash docker run -dt --name documentdb \\ -p 127.0.0.1:10260:10260 \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username '' \\ - --password '' + -e USERNAME='' \\ + -e PASSWORD='' \\ + ghcr.io/documentdb/documentdb/documentdb-local:latest \`\`\` +${documentdbLocalTelemetryNote} + If you prefer a host installation instead of Docker, use the [Linux Packages Quick Start](/docs/getting-started/packages) on a distribution in the current release matrix. ## ${vscodeExistingConnectionSectionTitle} @@ -818,7 +859,7 @@ For extension-specific help or bugs: ## Next steps -- [DocumentDB for VS Code docs](https://github.com/microsoft/vscode-documentdb/tree/main/docs) +- [Documentation for the DocumentDB extension for Visual Studio Code](https://github.com/microsoft/vscode-documentdb/tree/main/docs) - [Docker Quick Start](/docs/getting-started/docker) - [Linux Packages Quick Start](/docs/getting-started/packages) - [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart) @@ -851,11 +892,13 @@ export DOCUMENTDB_PASSWORD='' docker run -dt --name documentdb \\ -p 127.0.0.1:10260:10260 \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username "\${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME}" \\ - --password "\${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD}" + -e USERNAME="\${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME}" \\ + -e PASSWORD="\${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD}" \\ + ghcr.io/documentdb/documentdb/documentdb-local:latest \`\`\` +${documentdbLocalTelemetryNote} + Wait for the readiness banner in \`docker logs documentdb\` before connecting; see [Docker Quick Start](/docs/getting-started/docker#verify-the-container). ## Create a project @@ -926,7 +969,10 @@ async function main() { } } -main().catch(console.error); +main().catch((error) => { + console.error(error); + process.exitCode = 1; +}); \`\`\` Run the script: @@ -985,11 +1031,13 @@ export DOCUMENTDB_PASSWORD='' docker run -dt --name documentdb \\ -p 127.0.0.1:10260:10260 \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username "\${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME}" \\ - --password "\${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD}" + -e USERNAME="\${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME}" \\ + -e PASSWORD="\${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD}" \\ + ghcr.io/documentdb/documentdb/documentdb-local:latest \`\`\` +${documentdbLocalTelemetryNote} + Wait for the readiness banner in \`docker logs documentdb\` before connecting; see [Docker Quick Start](/docs/getting-started/docker#verify-the-container). ## Create a virtual environment (optional) @@ -1141,11 +1189,13 @@ Skip this if you installed Linux packages or already have a running instance. If \`\`\`bash docker run -dt --name documentdb \\ -p 127.0.0.1:10260:10260 \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username '' \\ - --password '' + -e USERNAME='' \\ + -e PASSWORD='' \\ + ghcr.io/documentdb/documentdb/documentdb-local:latest \`\`\` +${documentdbLocalTelemetryNote} + Replace the placeholders with your own credentials. Wait for the readiness banner in \`docker logs documentdb\` before connecting; see [Docker Quick Start](/docs/getting-started/docker#verify-the-container). ## Connect and verify the connection @@ -1155,7 +1205,7 @@ Use your existing instance's credentials. The certificate bypass is for **local \`\`\`bash mongosh localhost:10260 \\ -u '' \\ - -p '' \\ + -p \\ --authenticationMechanism SCRAM-SHA-256 \\ --tls \\ --tlsAllowInvalidCertificates @@ -1222,7 +1272,7 @@ Then pass your certificate file to \`mongosh\`: \`\`\`bash mongosh localhost:10260 \\ -u '' \\ - -p '' \\ + -p \\ --authenticationMechanism SCRAM-SHA-256 \\ --tls \\ --tlsCAFile ~/documentdb-cert.pem @@ -1250,75 +1300,14 @@ If \`mongosh\` does not connect on the first try: - [Samples Gallery](/samples) `; -const documentdbLocalDataInitializationContent = `## Container image tags - -The \`latest\` tag is a convenience alias. Pin an explicit tag for anything reproducible: - -| Tag | Contents | -|---|---| -| \`ghcr.io/documentdb/documentdb/documentdb-local:pg18-0.117.0\` | DocumentDB 0.117.0 on PostgreSQL 18 | -| \`…:pg17-0.117.0\` | DocumentDB 0.117.0 on PostgreSQL 17 | -| \`…:pg16-0.117.0\` · \`…:pg15-0.117.0\` | PostgreSQL 16 and 15 | -| \`…:pg15-1.0-rc2\` · \`…:pg16-1.0-rc2\` · \`…:pg17-1.0-rc2\` · \`…:pg18-1.0-rc2\` | [v1.0-RC2](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2), for testing only, with [no fixes to RC2 and no upgrade path](/docs/getting-started/release-candidate). No date for 1.0 yet. Use a new, empty data volume. Sends anonymous usage telemetry by default; see the [privacy statement](https://github.com/documentdb/documentdb/blob/v1.0-RC2/documentdb-local/PRIVACY.md) to opt out. | -| \`…:latest\` | Currently identical to \`pg17-0.117.0\` | - -> \`latest\` tracks **PostgreSQL 17**, while the \`documentdb\` package on Linux pins -> **PostgreSQL 18**. If you evaluate in Docker and then deploy from packages, you change -> major version unless you pin the tag deliberately. - -Every image records what it was built from: - -\`\`\`bash -docker run --rm --entrypoint cat ghcr.io/documentdb/documentdb/documentdb-local:pg18-0.117.0 /version.txt -\`\`\` - -## Data initialization - -DocumentDB Local starts **empty**. Pass \`--init-data true\` to seed the \`StoreData\` database -with the \`stores\` and \`ratings\` collections: - -\`\`\`bash -docker run -dt -p 127.0.0.1:10260:10260 --name documentdb \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username '' --password '' --init-data true -\`\`\` - -Seeding happens once per data volume, on a fresh volume. Existing volumes are not migrated -automatically; re-create the volume to seed again. - -### Control initialization behavior - -| Requirement | Arg | Env | Default | Description | -|---|---|---|---|---| -| Load built-in sample data | \`--init-data [true\\|false]\` | \`INIT_DATA\` | \`false\` | Seed the \`StoreData\` sample collections on a fresh data volume. | -| Skip built-in sample data | \`--skip-init-data\` | \`SKIP_INIT_DATA\` | — | Legacy alias for \`--init-data false\`. Does not affect \`--init-data-path\`. | -| Run custom initialization scripts | \`--init-data-path [PATH]\` | \`INIT_DATA_PATH\` | \`/init_doc_db.d\` | Execute every \`.js\` file in the mounted directory with \`mongosh\`. | - -The built-in sample dataset currently includes 41,505 store documents and 2 rating documents. - -### Use custom initialization scripts - -\`\`\`bash -docker run -dt --name documentdb \\ - -p 127.0.0.1:10260:10260 \\ - -v /path/to/init/scripts:/init_doc_db.d \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username '' \\ - --password '' \\ - --init-data-path /init_doc_db.d -\`\`\` - -When \`--init-data-path\` is provided, DocumentDB Local skips the built-in sample data -and runs only the scripts you mounted. -`; - const gettingStartedIndexArchitectureContent = `## Architecture Components -DocumentDB consists of three primary components: +DocumentDB consists of four primary components: 1. **pg_documentdb_core**: Core PostgreSQL extension that provides native BSON storage, field access, and indexing primitives. 2. **pg_documentdb**: Public API surface that implements document commands, CRUD operations, query execution, and index management. 3. **pg_documentdb_gw**: Gateway that translates MongoDB wire protocol requests into PostgreSQL operations and handles authentication, sessions, and TLS. +4. **pg_documentdb_extended_rum**: The index access method behind DocumentDB's document indexes, required in 1.0. Together, these components let you use DocumentDB through MongoDB-compatible tools and drivers while still benefiting from PostgreSQL internals. `; @@ -1331,8 +1320,6 @@ Choose your environment once, create a working instance, then connect with the c 2. **Create a working instance.** Follow the [Docker Quick Start](/docs/getting-started/docker) or [Linux Packages Quick Start](/docs/getting-started/packages). Linux package installation has two stages: install packages, then run the setup wizard. Neither copying a command nor installing files alone proves the endpoint is ready. 3. **Insert and read your first document.** Use the [Visual Studio Code Quick Start](/docs/getting-started/vscode-quickstart), [Node.js Quick Start](/docs/getting-started/nodejs-setup), or [Python Quick Start](/docs/getting-started/python-setup). Keep the same running instance; no second server installation is needed. -Linux packages are pre-GA and support **fresh installation only**, not in-place upgrades from earlier releases. Removing packages preserves database files; reinstalling does not reset data. - For advanced control, [use an existing local PostgreSQL instance](/docs/linux-packages#adopt-an-existing-postgre-sql-instance) with administrator-managed configuration and restart, or [install the PostgreSQL extension only](/docs/linux-packages#install-the-postgre-sql-extension-only). Extension-only installation does not install the gateway, so apps and drivers cannot connect; you use it through SQL. `; @@ -1470,10 +1457,6 @@ function normalizeArticle(section: string, file: string, frontmatter: Record +
+
+
+

Generally available · October 19, 2026

+

DocumentDB 1.0

+

+ The open-source, MongoDB-compatible document database built on PostgreSQL. +

+

+ Our first generally available release focuses on security, stability and correctness. MIT licensed, + with native BSON storage on PostgreSQL. +

+
+ + Install DocumentDB 1.0 + + + Read the announcement + +
+
+
+ +
+
+
+
+

A stabilization release

+

What's new in 1.0

+
+ + Full changelog + +
+
+ {highlights.map((item) => ( +
+

{item.title}

+

{item.description}

+ {item.href && ( + + {item.linkLabel} + + )} +
+ ))} +
+
+
+ +
+
+

Get started

+

Get started with DocumentDB 1.0

+
+
+

Docker

+

+ DocumentDB 1.0 on PostgreSQL 17; images for PostgreSQL 15 to 18 are published too. With Docker + running, replace the username and password, then run the command. On Windows, run it in WSL. +

+ + + + Docker quick start + +
+ +
+

Linux packages

+

+ Ubuntu 24.04 and EL9, PostgreSQL 17 or 18, amd64 or arm64, from the documentdb.io APT and YUM + repositories. On a clean host: +

+ + + apt and dnf commands + +
+ +
+

VS Code

+

+ The DocumentDB extension for Visual Studio Code 1.0 sets up DocumentDB Local for you, then lets you browse, query and copy + data between connections. Needs desktop VS Code and Docker running. +

+ + Open setup in VS Code + +

+ Don't have VS Code?{" "} + Download it first. +

+ + VS Code quick start + +
+ +
+

Kubernetes

+

+ The DocumentDB Kubernetes Operator 1.0.0 is generally available alongside the engine. The quick start prepares a + cluster, installs cert-manager and the operator, and creates your first DocumentDB database. +

+ + Deploy on Kubernetes + + + About the operator + +
+
+
+
+ +
+
+
+

Upgrading

+

Moving to 1.0

+
    +
  • + Linux packages from v0.116 or v0.117 upgrade in + place. Upgrade steps +
    • +
  • + Containers: start the 1.0 image on a new volume + and reload your data; a newer image does not update an existing volume.{" "} + Upgrading the image +
    • +
  • + Release candidates have no upgrade path. Start + from a clean host or volume. +
    • +
+

+ Known issues + {" · "} + Release notes + {" · "} + v1.0-0 on GitHub +

+
+ +
+

Read more

+

From the blog

+
+ {readMore.map((item) => ( + + + + {item.label} + + {item.title} + + + + ))} +
+
+
+
+ +
+
+

Built in the open

+

+ Try 1.0 with a workload that matters to you, and tell us what you find. +

+ +
+
+ + ); +} diff --git a/articles/content.yml b/articles/content.yml index 84b6781..752f773 100644 --- a/articles/content.yml +++ b/articles/content.yml @@ -4,7 +4,7 @@ landing: links: - title: Getting Started with DocumentDB link: /docs/getting-started - - title: DocumentDB Kubernetes Operator (Preview) + - title: DocumentDB Kubernetes Operator link: /docs/kubernetes-operator - title: API Reference link: /docs/reference diff --git a/blogs/_config.yml b/blogs/_config.yml index fe6661a..42c68cb 100644 --- a/blogs/_config.yml +++ b/blogs/_config.yml @@ -3,6 +3,10 @@ description: Insights, updates, and deep dives into the world of document databa # Shared external links. The Next.js app keeps the same values in # app/services/externalLinks.ts; update both when one changes. discord_url: https://discord.gg/vH7bYu524D +# Where the 1.0 banner and update notes send readers: a blog path (resolved +# under baseurl) or an absolute URL. app/services/externalLinks.ts holds the +# site-root form. +release_announcement_url: /posts/documentdb-1-0/ baseurl: /blogs # Absolute host for og:url, og:image, and the Atom feed's permanent IDs. url: "https://documentdb.io" diff --git a/blogs/_includes/post-card.html b/blogs/_includes/post-card.html index 79ffd0f..80f49e1 100644 --- a/blogs/_includes/post-card.html +++ b/blogs/_includes/post-card.html @@ -10,6 +10,11 @@ {% assign meta_text = category.meta | default: "Community article" %} {% endif %} +{% assign is_release = false %} +{% if post.release_post %} + {% assign is_release = true %} +{% endif %} + {% if post.uri %} {% assign href = post.uri %} {% assign is_external = true %} @@ -20,27 +25,10 @@
- {% if post.cover_image %} - {% if post.cover_image contains '://' %} - {% assign cover_image_src = post.cover_image %} - {% else %} - {% assign cover_image_src = post.cover_image | relative_url %} - {% endif %} -
- {{ post.cover_image_alt | default: post.title | escape }} -
- {% endif %} -
@@ -48,6 +36,7 @@

{{ category.label | default: post.category }}

{{ meta_text }}

+ {% if is_release %}1.0 release{% endif %}

{{ post.title }}

@@ -68,6 +57,7 @@

{{ post.title }}

{% if include.featured %}Read featured post{% else %}Read post{% endif %} {% endif %} + {% if is_external %}{% endif %}
diff --git a/blogs/_layouts/default.html b/blogs/_layouts/default.html index f8abab1..76d69fe 100644 --- a/blogs/_layouts/default.html +++ b/blogs/_layouts/default.html @@ -40,7 +40,12 @@ - {% assign site_root = site.baseurl | replace: '/blogs', '' %} + {% assign blog_base = site.baseurl %} + {% assign blog_base_last = blog_base | slice: -1, 1 %} + {% if blog_base_last == '/' %}{% assign blog_base_end = blog_base | size | minus: 1 %}{% assign blog_base = blog_base | slice: 0, blog_base_end %}{% endif %} + {% assign site_root = blog_base %} + {% assign blogs_at = blog_base | size | minus: 6 %} + {% if blogs_at >= 0 %}{% assign blogs_tail = blog_base | slice: blogs_at, 6 %}{% if blogs_tail == '/blogs' %}{% assign site_root = blog_base | slice: 0, blogs_at %}{% endif %}{% endif %} {% if site_root == '' %} {% assign site_root = '/' %} {% endif %} @@ -63,7 +68,13 @@ Blogs {% endcapture %} + {% assign release_page_href = site_root | append: '/v1/' | replace: '//', '/' %}
+ + New + DocumentDB 1.0 is here. + See what's new +
diff --git a/blogs/_posts/2026-03-19-meet-documentdb-kubernetes-operator.md b/blogs/_posts/2026-03-19-meet-documentdb-kubernetes-operator.md index 8908db1..2829487 100644 --- a/blogs/_posts/2026-03-19-meet-documentdb-kubernetes-operator.md +++ b/blogs/_posts/2026-03-19-meet-documentdb-kubernetes-operator.md @@ -2,7 +2,7 @@ title: Meet the DocumentDB Kubernetes Operator description: Preview an open-source operator that brings declarative deployment, secure connectivity, high availability, backup and restore, and automated multi-cloud deployment to DocumentDB on Kubernetes. date: 2026-03-19 -featured: true +featured: false author: DocumentDB team category: documentdb-blog tags: @@ -11,6 +11,8 @@ tags: - DocumentDB - Open Source --- + +**Update, October 19, 2026:** The DocumentDB Kubernetes Operator 1.0.0 is generally available. The `documentdb.io/preview` API version and the `preview` in the docs URLs are names kept for compatibility. See [DocumentDB 1.0 on Kubernetes]({{ '/posts/kubernetes-operator-versioning/' | relative_url }}). The DocumentDB Kubernetes Operator brings MongoDB API compatible document database management to any Kubernetes cluster — with declarative deployment, automatic high availability, backup and restore, TLS, and a documented multi-cloud deployment path across AKS, GKE, and EKS — all fully open source under the MIT license. [DocumentDB](https://github.com/documentdb/documentdb) is an open-source, MongoDB API compatible document database engine built on PostgreSQL, governed by the Linux Foundation. It powers vCore-based Azure Cosmos DB for MongoDB and provides native support for BSON data types, aggregation pipelines, change streams, vector search, and ACID transactions. The Kubernetes Operator runs and manages DocumentDB on Kubernetes: when you deploy a cluster, it creates and manages PostgreSQL instances, the DocumentDB Gateway, and the supporting Kubernetes resources around them. The gateway translates the MongoDB wire protocol, so existing MongoDB drivers — PyMongo, Node.js, Java, Go, C++ — work without code changes, and teams can keep using familiar clients such as `mongosh`. diff --git a/blogs/_posts/2026-09-10-linux-packages.md b/blogs/_posts/2026-09-10-linux-packages.md index 8199aaf..a7aa495 100644 --- a/blogs/_posts/2026-09-10-linux-packages.md +++ b/blogs/_posts/2026-09-10-linux-packages.md @@ -2,7 +2,7 @@ title: "Linux packages for DocumentDB: start simple, keep control" description: Install DocumentDB on Linux with apt or dnf and guided setup. Start with the complete stack, use your own local PostgreSQL, or install only the extension. date: 2026-09-10 -featured: true +featured: false author: DocumentDB team category: documentdb-blog tags: @@ -12,7 +12,12 @@ tags: - APT - RPM --- -{% assign site_root = site.baseurl | replace: '/blogs', '' %} +{% assign blog_base = site.baseurl %} +{% assign blog_base_last = blog_base | slice: -1, 1 %} +{% if blog_base_last == '/' %}{% assign blog_base_end = blog_base | size | minus: 1 %}{% assign blog_base = blog_base | slice: 0, blog_base_end %}{% endif %} +{% assign site_root = blog_base %} +{% assign blogs_at = blog_base | size | minus: 6 %} +{% if blogs_at >= 0 %}{% assign blogs_tail = blog_base | slice: blogs_at, 6 %}{% if blogs_tail == '/blogs' %}{% assign site_root = blog_base | slice: 0, blogs_at %}{% endif %}{% endif %} Docker remains the fastest way to evaluate DocumentDB on Linux, macOS, or Windows. When you cannot use Docker, or need control over PostgreSQL, services, and configuration on a Linux host, Linux packages give you another option: familiar package managers, guided setup, and a choice about how much of the stack you manage. diff --git a/blogs/_posts/2026-09-11-documentdb-on-github-open-source-friday.md b/blogs/_posts/2026-09-11-documentdb-on-github-open-source-friday.md new file mode 100644 index 0000000..60e7629 --- /dev/null +++ b/blogs/_posts/2026-09-11-documentdb-on-github-open-source-friday.md @@ -0,0 +1,52 @@ +--- +title: "DocumentDB on GitHub Open Source Friday: building toward v1.0" +description: "Watch the September 11 conversation with Patty Chow about running DocumentDB locally, developer choice, and contributing to the project." +date: 2026-09-11 +featured: false +author: Patty Chow +category: documentdb-blog +tags: + - DocumentDB + - Open Source + - GitHub + - Community + - "1.0" +--- + +What should developers expect from an open-source document database, and how can they help shape it? On GitHub's Open Source Friday, Patty Chow joined host Sarah to discuss DocumentDB's work toward v1.0 and demonstrate getting started locally. + +The conversation covered familiar MongoDB workflows on PostgreSQL, the experience of using DocumentDB through VS Code, and the role of feedback from people trying the project. Viewers also asked where DocumentDB fits alongside MongoDB and PostgreSQL with pgvector. + +[Watch the full episode on GitHub's YouTube channel](https://www.youtube.com/watch?v=TkxGupjwdxE). + +## A local starting point + +The [demo introduction begins at 16:31](https://www.youtube.com/watch?v=TkxGupjwdxE&t=991s). Using a local Docker instance and the DocumentDB extension for VS Code, Patty walks through creating a database and collection, importing home-listing data, and querying it in a playground. + +That workflow gives developers a way to explore the project in an editor they already use. The sample data makes it possible to inspect documents and try queries without first building a complete application. The episode demonstrates the introductory steps of a larger booking-agent sample; it does not walk through the full application or its vector-search features. + +For an up-to-date setup, use the [getting-started guide](https://documentdb.io/docs/getting-started/). Installation details can change after a recording. + +## What the work toward v1.0 is meant to improve + +At [14:27](https://www.youtube.com/watch?v=TkxGupjwdxE&t=867s), the discussion turns to what makes a release ready for more people to build on. Patty describes work on collation and aggregation behavior, query planning and indexes, and easier installation. + +These are practical concerns for an application team evaluating a database. Setup needs to be understandable, queries need to behave as expected, and users need enough information to judge whether a particular release fits their workload. + +The episode discusses goals for v1.0. For current release status and supported usage, consult the [release notes](https://github.com/documentdb/documentdb/releases) rather than treating the recording as a production-support statement. + +## Giving developers another option + +A [viewer question at 22:54](https://www.youtube.com/watch?v=TkxGupjwdxE&t=1374s) asks why someone familiar with both MongoDB and PostgreSQL would choose DocumentDB. The answer covers DocumentDB's permissive MIT license and PostgreSQL foundation, alongside its support for MongoDB drivers and queries. + +Later, at [35:00](https://www.youtube.com/watch?v=TkxGupjwdxE&t=2100s), Patty acknowledges that PostgreSQL with pgvector can remain a good fit for developers already comfortable with that setup. DocumentDB offers another approach for applications built around document data and MongoDB-style access. + +The longer-term discussion includes collaboration across cloud companies and an ambition to improve interoperability between document databases. That is a direction to explore with other builders, not an announcement of a completed standard. + +## Contributing starts with trying it + +At [54:09](https://www.youtube.com/watch?v=TkxGupjwdxE&t=3249s), Patty explains how evaluating the project and sharing feedback can help its development. A question about installation or a reproducible example of unexpected behavior gives maintainers something concrete to work with. + +You do not need to know how to fix the database before reporting a problem. Describe what you were trying to do, include the relevant versions, and show what happened compared with the result you expected. + +Read the [contribution guide](https://github.com/documentdb/documentdb/blob/main/CONTRIBUTING.md) for the project's discussion channels and contribution process. The episode is a useful introduction; trying a workload of your own is the next step. diff --git a/blogs/_posts/2026-09-23-documentdb-name-disambiguation.md b/blogs/_posts/2026-09-23-documentdb-name-disambiguation.md index 3b8d5d6..f09b935 100644 --- a/blogs/_posts/2026-09-23-documentdb-name-disambiguation.md +++ b/blogs/_posts/2026-09-23-documentdb-name-disambiguation.md @@ -30,8 +30,8 @@ tags: | **Azure Cosmos DB for NoSQL** | The Cosmos DB native API, originally shipped as the DocumentDB "SQL API", later "Core (SQL) API", renamed "for NoSQL" in 2022. | Direct descendant of the *historical* Azure DocumentDB API. Unrelated to this project. | Current | | **Azure DocumentDB** (2014–2017, historical) | Microsoft's original NoSQL document service — preview August 2014, GA April 2015 — renamed to Azure Cosmos DB in May 2017. | **No relationship** to the open-source DocumentDB project or to today's Azure DocumentDB, beyond reuse of the name. | **Retired name** | | **DocumentDB Local** | Container distribution of the open-source engine for local development. | Part of the project. | Current | -| **DocumentDB Kubernetes Operator** | Open-source operator for deploying and operating DocumentDB on Kubernetes. | Part of the project. | Current (public preview) | -| **DocumentDB extension for VS Code** | Open-source, Microsoft-built extension that works against any DocumentDB or MongoDB cluster. | Tooling for the project. | Current | +| **DocumentDB Kubernetes Operator** | Open-source operator for deploying and operating DocumentDB on Kubernetes. | Part of the project. | Current | +| **DocumentDB extension for Visual Studio Code** | Open-source, Microsoft-built extension that works against any DocumentDB or MongoDB cluster. | Tooling for the project. | Current | | **MongoDB** (MongoDB, Inc.) | A separate commercial database product. | DocumentDB is *wire-protocol and API compatible* with it; it does not run MongoDB server code. | Current | ## The five distinctions that actually cause confusion diff --git a/blogs/_posts/2026-10-01-versioning.md b/blogs/_posts/2026-10-01-versioning.md index efa79d4..185b44c 100644 --- a/blogs/_posts/2026-10-01-versioning.md +++ b/blogs/_posts/2026-10-01-versioning.md @@ -2,7 +2,7 @@ title: "Long-term support or development? An explanation of DocumentDB's versioning" description: A comparison of DocumentDB's long-term support, development, and release-candidate builds date: 2026-10-01 -featured: true +featured: false author: DocumentDB team category: documentdb-blog tags: @@ -12,6 +12,8 @@ tags: - Version --- +**Update, October 19, 2026:** DocumentDB 1.0 is now available. [Read the announcement]({{ site.release_announcement_url | relative_url }}). + DocumentDB is releasing v1.0-RC1 for testing. This is a release candidate preceding the full 1.0 release. Following the full release, DocumentDB will split the main development branch that will continue with 1.1 and beyond from the LTS branch that will stay at 1.0. This is to ensure there is a stable version of the platform for users who don't need the latest features. @@ -27,27 +29,9 @@ These experimental versions are not intended for long-term use, nor will they be ### Release candidate installation -> **Update:** [v1.0-RC2](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2) replaces RC1 for testing. Use `rc2` and `v1.0-RC2` in place of `rc1` and `v1.0-RC1` below. The RC2 image sends anonymous usage telemetry by default; add `-e DOCUMENTDB_USAGE_TELEMETRY=false` to opt out. - -With Docker: - -```bash -docker run -dt --name docdb-rc1 -p 127.0.0.1:10260:10260 \ - ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0-rc1 \ - --username '' --password '' -``` - -Or on Ubuntu 24.04 or RHEL 9: - -```bash -curl -fsSLo documentdb-install.sh \ - https://documentdb.io/install.sh && -sudo sh documentdb-install.sh --version v1.0-RC1 -``` - -See [Try the 1.0 release candidate](https://documentdb.io/docs/getting-started/release-candidate/) for details. +> **Update, October 19, 2026:** The 1.0 release candidates are retired and no longer get fixes. [Install DocumentDB 1.0](https://documentdb.io/packages/) instead. A host or data volume that ran an RC has no upgrade path to 1.0; start from a clean one. -If you find any problems with the RC, please [create an issue on GitHub](https://github.com/documentdb/documentdb/issues). +If you find any problems, please [create an issue on GitHub](https://github.com/documentdb/documentdb/issues). ## Definition of support diff --git a/blogs/_posts/2026-10-07-why-document-databases-need-more-than-one-implementation.md b/blogs/_posts/2026-10-07-why-document-databases-need-more-than-one-implementation.md new file mode 100644 index 0000000..504fa6c --- /dev/null +++ b/blogs/_posts/2026-10-07-why-document-databases-need-more-than-one-implementation.md @@ -0,0 +1,57 @@ +--- +title: "Why document databases need more than one implementation" +description: "How DocumentDB approaches developer choice, MongoDB compatibility, and participation across organizations as it works toward v1.0." +date: 2026-10-07 +featured: false +author: Patty Chow +category: documentdb-blog +tags: + - DocumentDB + - Open Source + - MongoDB Compatibility + - Community +--- + +**Update, October 19, 2026:** DocumentDB 1.0 is now available. [Read the announcement]({{ site.release_announcement_url | relative_url }}). + +Choosing a document database is a long-term investment in how an application works. A team learns a query language, adopts drivers, and builds around particular behaviors. Those choices become part of the application, from routine reads to the way it recovers after a failed write. + +Developers should be able to preserve more of that work when their infrastructure needs change. They may want to run a workload themselves, move it to another provider, or choose a different database implementation. Doing so should not require starting over. + +DocumentDB is an open-source document database built on PostgreSQL, designed to support MongoDB drivers and queries. As the project works toward v1.0, we want to make that choice more practical for the people building applications and operating them. + +## Familiar tools, more room to choose + +MongoDB has given developers a widely used way to work with document data. Familiar drivers and query patterns are worth preserving. Alternative implementations give developers a chance to keep using that knowledge while evaluating different approaches to storage and deployment. + +The important test is what happens to an application. Can its driver connect? Does a query return the expected result, including the types and ordering it relies on? What happens when a request fails and the client retries? + +Compatibility has to account for those details. Teams also need to evaluate operational differences, such as backup and recovery, before moving a workload. A successful connection or a short CRUD demo cannot answer every migration question. + +For DocumentDB, useful progress means more applications behaving as expected, with differences documented clearly enough for developers to make an informed decision. A reproducible report of an unexpected result helps establish where that work is needed. + +## Source code others can build on + +DocumentDB's MIT license allows others to use, modify, and redistribute the project's code under its terms. Developers can inspect the implementation, adapt it to their needs, or build a service around it. PostgreSQL provides a foundation with an existing ecosystem of tools and operational knowledge. + +Those choices make several forms of participation possible. An application team may need a particular query behavior. A database provider may want to offer a managed service. An operator may contribute a deployment fix that makes the project easier to run. + +These participants will not always have the same priorities. The project benefits when their experience exposes assumptions that the original team would otherwise miss. + +## A project worth contributing to + +DocumentDB is a Linux Foundation project. Its [charter](https://github.com/documentdb/documentdb/blob/main/GOVERNANCE.md) provides for open participation regardless of competitive interests, with technical oversight through the Technical Steering Committee. + +That framework needs to be useful in everyday development. Contributors should be able to understand how a proposal is considered and where to discuss a different approach. Their work should receive specific credit, including the testing, documentation, and review that make code usable. + +A company considering whether to invest engineering time needs a reason to believe its contribution can matter. Helping another organization improve the shared implementation should also help it serve its own users. That is a more sustainable basis for collaboration than asking for support for a project in the abstract. + +Shared compatibility tests are one place to explore that collaboration. A documented test case can help multiple implementations examine the same behavior while keeping their own architectures and priorities. Such work could inform broader interoperability efforts over time. It would need agreement on scope and expected behavior; a compatibility claim alone does not establish an open standard. + +## Help evaluate the path to v1.0 + +The [v1.0 release candidate](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC1) is available for testing. It precedes the final release and should be evaluated on a fresh, short-lived instance rather than used as a supported production release. + +Try a workload that matters to you. If something behaves unexpectedly, share a minimal example, the versions involved, and the result you expected. If the installation instructions leave something unclear, that is useful feedback too. + +Start with the [getting started guide](https://documentdb.io/docs/getting-started/) and the [contribution guide](https://github.com/documentdb/documentdb/blob/main/CONTRIBUTING.md). Your application can help identify the next compatibility gap or usability problem the project needs to address. diff --git a/blogs/_posts/2026-10-19-documentdb-1-0.md b/blogs/_posts/2026-10-19-documentdb-1-0.md new file mode 100644 index 0000000..e4416a7 --- /dev/null +++ b/blogs/_posts/2026-10-19-documentdb-1-0.md @@ -0,0 +1,53 @@ +--- +title: "DocumentDB 1.0 is here" +description: The first generally available release of DocumentDB, the MIT-licensed, MongoDB-compatible document database built on PostgreSQL. +date: 2026-10-19 00:01:02 -0700 +featured: true +release_post: true +author: DocumentDB team +category: documentdb-blog +tags: + - DocumentDB + - "1.0" + - Release +--- + +DocumentDB 1.0 is available today. It is the first generally available release of DocumentDB: an MIT-licensed document database that speaks the MongoDB wire protocol and stores native BSON in PostgreSQL. Most MongoDB drivers, tools and queries work against it unchanged, and the data lives in a database you can run, inspect and operate like any other PostgreSQL deployment. + +The [v1.0-0 release](https://github.com/documentdb/documentdb/releases/tag/v1.0-0) is the same code as the second release candidate, which the community tested over the past weeks. Thank you to everyone who installed an RC, ran a workload against it and filed what they found. + +## What's in 1.0 + +1.0 is a stabilization release. Most of the work since v0.117 makes existing behavior correct and safe under load, rather than adding surface area. Among the [changes in this release](https://github.com/documentdb/documentdb/blob/v1.0-0/CHANGELOG.md): + +- **Security fixes.** `find` and `aggregate` with `batchSize: 0` now run the permission check, `$merge` and `$out` require write permission on their target collection, and `createUser` and `updateUser` reject passwords that fail SASLprep. +- **Stability.** Fixes for backend crashes in `$getField`/`$setField`, `$firstN`/`$lastN` and `$documents` inside `$facet`, a deadlock between concurrent `dropIndexes`, and several RUM index vacuum and ordered-scan issues. The gateway now returns specific, retryable error codes instead of `InternalError` and exits with an error instead of panicking when PostgreSQL is unreachable at startup. +- **Collation, opt-in.** With `documentdb_core.enableCollation` on, more operators honor collation, including `count`, the `$stdDevPop`, `$stdDevSamp`, `$median` and `$percentile` accumulators, and the symbol BSON type. Collation is off by default, and `distinct`, `findAndModify` and `update` don't support it yet; see the [known issues](https://documentdb.io/docs/getting-started/release-notes-1.0/#known-issues). +- **Geospatial.** `$near`, `$nearSphere` and `$geoNear` no longer fail on nearly coincident points or at longitude -180 on a `2dsphere` index. + +## Get DocumentDB 1.0 + +- **Docker**, on Linux, macOS or Windows: `ghcr.io/documentdb/documentdb/documentdb-local` with tags `pg15-1.0.0` through `pg18-1.0.0`; `latest` is PostgreSQL 17. Start with the [Docker Quick Start](https://documentdb.io/docs/getting-started/docker/). +- **Linux packages** for Ubuntu 24.04 and EL9 on PostgreSQL 17 or 18, amd64 or arm64, from the documentdb.io APT and YUM repositories or the clean-host installer. See [Install DocumentDB](https://documentdb.io/packages/). +- The **DocumentDB extension for Visual Studio Code 1.0** sets up DocumentDB Local for you. [Read about the release]({{ '/posts/documentdb-for-vs-code-1-0/' | relative_url }}). +- **Kubernetes**: the DocumentDB Kubernetes Operator 1.0.0 is generally available alongside the engine. See [DocumentDB 1.0 on Kubernetes]({{ '/posts/kubernetes-operator-versioning/' | relative_url }}). + +## Usage telemetry in the container image + +Starting with 1.0, the `documentdb-local` container image sends usage telemetry by default: the image version, operating system and CPU architecture, once at startup and then hourly. It never sends your data, queries, names or credentials. The data goes to [Scarf](https://scarf.sh), which sees the network address each request comes from, so don't assume it is anonymous. + +To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false` (or `-e DO_NOT_TRACK=1`) to `docker run`. The Linux packages, the extensions and the gateway collect nothing. The [privacy statement](https://github.com/documentdb/documentdb/blob/v1.0-0/documentdb-local/PRIVACY.md) has the details. + +## Upgrading + +- **Linux packages from v0.116 or v0.117** upgrade in place. Upgrade the whole stack together, then update the extensions in every database that has DocumentDB. Follow [Upgrading](https://documentdb.io/docs/linux-packages/#upgrading). +- **Containers**: a 1.0 image started on an existing data volume does not update the DocumentDB schema in it ([documentdb#773](https://github.com/documentdb/documentdb/issues/773)). Start 1.0 on a new volume and reload your data; see [Upgrading the image](https://documentdb.io/docs/documentdb-local/#upgrading-the-image). +- **Release candidates** have no upgrade path. Move RC hosts and volumes to a clean install of 1.0. + +The [1.0 release notes](https://documentdb.io/docs/getting-started/release-notes-1.0/#upgrading) cover every upgrade path and the [known issues](https://documentdb.io/docs/getting-started/release-notes-1.0/#known-issues). The [v1.0-0 release](https://github.com/documentdb/documentdb/releases/tag/v1.0-0) has the packages and checksums. + +## What's next + +With 1.0 out, the project plans a long-term support track alongside a development track for 1.1 and beyond. The [proposed policy]({{ '/posts/versioning/' | relative_url }}) is still under discussion in [documentdb/documentdb#597](https://github.com/documentdb/documentdb/pull/597). + +Try 1.0 with a workload that matters to you, and tell us what you find on [GitHub](https://github.com/documentdb/documentdb/issues) or [Discord]({{ site.discord_url }}). diff --git a/blogs/_posts/2026-10-19-documentdb-for-vs-code-1-0.md b/blogs/_posts/2026-10-19-documentdb-for-vs-code-1-0.md new file mode 100644 index 0000000..18d0c54 --- /dev/null +++ b/blogs/_posts/2026-10-19-documentdb-for-vs-code-1-0.md @@ -0,0 +1,78 @@ +--- +title: "DocumentDB Extension for Visual Studio Code 1.0: Run It Locally, Bring Your Data" +description: The DocumentDB extension for Visual Studio Code, a free, open-source DocumentDB GUI, reaches 1.0. Start DocumentDB Local in a few clicks, bring your data with copy and paste, and understand it with the Cluster Dashboard and Query Insights. +date: 2026-10-19 00:01:01 -0700 +featured: true +release_post: true +author: Tomasz Naumowicz and the team behind the DocumentDB extension for Visual Studio Code +category: documentdb-blog +cover_image: /assets/images/posts/documentdb-for-vs-code-1-0/hero.png +cover_image_alt: DocumentDB extension for Visual Studio Code 1.0 +tags: + - DocumentDB + - VS Code + - "1.0" + - GUI + - Tools +--- +Version 1.0 of the DocumentDB extension for Visual Studio Code is here. Released alongside [DocumentDB 1.0]({{ site.release_announcement_url | relative_url }}), the free, open-source extension is a **DocumentDB GUI** and MongoDB GUI, right in your editor. It works with DocumentDB, Azure DocumentDB and other MongoDB-compatible databases, wherever they run. + +The milestone reflects what we built across all the releases on the way to 1.0, over a little more than a year. Version 1.0 focuses on fixes and polish, and celebrates how far that experience has come. Here is the shortest path from reading about DocumentDB 1.0 to working with it: run it locally, bring your own data, and understand what you have. + +## Get started with DocumentDB 1.0 in minutes + +The quickest way to try DocumentDB 1.0 is **DocumentDB Local**, right from VS Code. If Docker is installed, open the Connections view, expand **Your own DocumentDB**, and select **Set up DocumentDB Local**. Keep the defaults and start it. + +The extension does the rest: it pulls the official DocumentDB image, creates a persistent volume so your data survives restarts, generates credentials, picks a free port, loads sample data, and saves a ready-to-use connection. No `docker run` command to assemble. From then on, you start, stop or restart the container from the same place, and if Docker isn't ready, the setup tells you exactly what's wrong and how to fix it. + +The DocumentDB Local image sends usage telemetry by default. The [privacy statement](https://github.com/documentdb/documentdb/blob/v1.0-0/documentdb-local/PRIVACY.md) explains what is sent and how to turn it off. + +![DocumentDB Local setup in VS Code with the Introduction, Configure, Set up and Done steps]({{ '/assets/images/posts/documentdb-for-vs-code-1-0/documentdb-local.png' | relative_url }}) + +## Bring your data with you + +Sample data is a good start, but your own data tells you more. With **copy and paste**, you move a collection between any two connections the same way you copy files: right-click a collection and choose **Copy Collection…**, then right-click a database on the same cluster or any other and choose **Paste Collection…**. + +That means a collection from MongoDB Atlas, Azure or a shared development cluster can land in your DocumentDB Local instance in a few clicks. If the target already has documents, you decide what happens with duplicates: stop, skip, overwrite, or give the pasted documents new IDs. The collection's indexes can come along too. + +![Copy and paste in three steps: copy the source collection, paste it into the target, then choose how to handle conflicts]({{ '/assets/images/posts/documentdb-for-vs-code-1-0/copy-and-paste.png' | relative_url }}) + +Copy and paste is built for development and small to medium datasets. For large production migrations, use a dedicated migration service. + +## See what you have + +Whether the data came from a sample, a copy or a production cluster, the first question is usually "what's in here?" The **Cluster Dashboard** answers it on one page: whether you're connected, the round-trip time, and an inventory of every database and collection with its storage size, index size and document count. Sort and filter the list, drill into a database, or create and delete databases and collections right there. + +![Cluster Dashboard showing connection status, storage and document metrics, and a filterable database inventory]({{ '/assets/images/posts/documentdb-for-vs-code-1-0/cluster-dashboard.png' | relative_url }}) + +## Understand how it runs + +Queries don't always come from you anymore. Whether you wrote one yourself or an AI agent suggested it, you still want to know how it runs. **Query Insights** explains it in three steps: the query plan, then execution statistics with a simple Good, Fair or Poor rating, and then optional AI recommendations from GitHub Copilot that explain what's happening and suggest changes you can apply directly. + +**Index management** sits right next to it, so understanding a query and fixing it happen in the same place. See which indexes are used and which are not, and hide an index first to check the impact before you delete it. + +![Query Insights streaming an AI performance analysis next to the query plan summary]({{ '/assets/images/posts/documentdb-for-vs-code-1-0/query-insights-streaming.png' | relative_url }}) + +## And there is more + +- **Find your clusters, wherever they run.** Service Discovery lists your databases on Azure, in Kubernetes (including clusters managed by the DocumentDB Kubernetes Operator) and in MongoDB Atlas, so you pick a cluster instead of copying connection strings. +- **Sign in once.** Use a username and password, or Microsoft Entra ID with your VS Code account or the managed identity of an Azure virtual machine. Every view uses the same connection. +- **Look at the data your way.** Browse documents in Table, Tree or JSON view, ask the next question in the Interactive Shell, or save queries in a Query Playground file. One click moves the same query between them, and everything is bundled with the extension. + +## A shared milestone, built in the open + +![The road to version 1.0 of the DocumentDB extension for Visual Studio Code, from v0.2 in May 2025 to 1.0 in October 2026]({{ '/assets/images/posts/documentdb-for-vs-code-1-0/road-to-1.0-illustrated.jpg' | relative_url }}) + +DocumentDB 1.0 is a milestone for the open-source database. Version 1.0 of the extension celebrates the developer experience around it, one that also works with the MongoDB-compatible databases you already run. + +We didn't get here alone. Eleven community developers contributed nearly 30 pull requests along the way, and many more of you shaped the extension with issue reports, accessibility reviews and bug bash findings. Thank you for helping us reach 1.0. + +> **Run it locally. Bring your data. Understand what you have.** That's the experience we have been building, release by release. + +## Try it + +**[Install the DocumentDB extension for Visual Studio Code from the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb)**, or search for "DocumentDB" in the VS Code Extensions view. + +- [Version 1.0 release notes](https://github.com/microsoft/vscode-documentdb/discussions/1012) (the full tour, with every feature explained) +- [Documentation](https://microsoft.github.io/vscode-documentdb/) +- [GitHub repository](https://github.com/microsoft/vscode-documentdb) diff --git a/blogs/_posts/2026-10-19-kubernetes-operator-versioning.md b/blogs/_posts/2026-10-19-kubernetes-operator-versioning.md new file mode 100644 index 0000000..acd4dbf --- /dev/null +++ b/blogs/_posts/2026-10-19-kubernetes-operator-versioning.md @@ -0,0 +1,91 @@ +--- +title: "DocumentDB 1.0 on Kubernetes" +description: How the DocumentDB Kubernetes Operator helps teams deploy and manage clusters as part of the DocumentDB 1.0 release +date: 2026-10-19 00:01:00 -0700 +featured: true +release_post: true +author: DocumentDB team +category: documentdb-blog +tags: + - DocumentDB + - Kubernetes + - Operator + - "1.0" + - Release +--- + +As part of the DocumentDB 1.0 announcement, we're highlighting the +[DocumentDB Kubernetes Operator][operator]: a Kubernetes-native way to deploy +and manage DocumentDB clusters. Alongside the DocumentDB Engine 1.0 release, +the operator gives teams already using Kubernetes a way to bring their document +database into the same operational workflows as their applications. + +## Describe your cluster, let the operator manage it + +The operator extends Kubernetes with Custom Resource Definitions (CRDs). You +describe the desired DocumentDB cluster in a Kubernetes manifest, and its +controllers reconcile the deployment toward that state. Instead of treating +database setup as a collection of one-off commands, you can keep cluster +configuration in version control and apply it through your existing deployment +process. + +Built on CloudNativePG, the operator brings a PostgreSQL foundation to DocumentDB +deployments and automates deployment, scaling, and cluster lifecycle management. +Helm charts provide a repeatable way to install and configure the operator itself. + +## Where the operator fits + +For application teams, the operator makes it easier to run a MongoDB-compatible +document database alongside Kubernetes-hosted services. For platform teams, it +provides a declarative interface for database infrastructure that fits existing +Kubernetes tooling and review processes. + +Its uses extend from development environments to deployments with more demanding +availability requirements: + +- **Repeatable environments:** Define cluster configuration in manifests so teams + can review changes and reproduce deployments. +- **Day-to-day operations:** Use the operator's automated deployment, scaling, + and lifecycle management rather than coordinating each Kubernetes resource + manually. +- **High availability:** Configure highly available clusters using the operator's + integration with CloudNativePG. +- **Cloud flexibility:** Use the project's deployment guides for Azure Kubernetes + Service and Amazon Elastic Kubernetes Service, or explore multi-region and + multi-cloud setups using fleet management and Istio. + +Multi-region and multi-cloud deployments require additional infrastructure and +configuration; the repository includes guides and examples for those setups. +The operator is the cluster-management layer, not a replacement for planning +storage, networking, and availability around your workload. + +## A brief note on versioning + +With Engine 1.0, DocumentDB plans a long-term support (LTS) track for teams that +want a stable feature set with security patches, and a development track for teams +that want newer capabilities and can keep up with minor releases. Release +candidates are for testing, not long-term deployments. Our +[October 1 post on DocumentDB versioning][versioning] explains the proposed +support policy and upgrade paths. + +Operator 1.0.0 is generally available alongside Engine 1.0, but the operator and engine keep +separate version numbers. Coordinating their releases does not make their upgrades +interchangeable: choose an operator +release compatible with your engine and Kubernetes versions, and follow the +relevant upgrade guidance for each. + +## Get started + +Start with the [operator installation guide][installation] for prerequisites and +Helm setup, then follow the [quick start][quickstart] to deploy your first cluster. +Pin an explicit Helm chart version, such as `--version 1.0.0`, for repeatable +installations and review that release's compatibility requirements. + +Explore the [repository][operator] for platform-specific examples, report issues, +or contribute. As DocumentDB reaches 1.0, the operator brings its database +capabilities into the Kubernetes workflows your team already uses. + +[operator]: https://github.com/documentdb/documentdb-kubernetes-operator +[versioning]: {{ '/posts/versioning/' | relative_url }} +[installation]: https://documentdb.io/documentdb-kubernetes-operator/latest/preview/getting-started/before-you-start/ +[quickstart]: https://documentdb.io/documentdb-kubernetes-operator/latest/preview/#quickstart diff --git a/blogs/assets/blog.css b/blogs/assets/blog.css index d9d15b9..7ed2572 100644 --- a/blogs/assets/blog.css +++ b/blogs/assets/blog.css @@ -35,6 +35,54 @@ a { text-decoration: none; } +.release-bar { + display: block; + padding: 0.5rem 1rem; + background: linear-gradient(90deg, rgba(16, 185, 129, 0.2), rgba(59, 130, 246, 0.2), rgba(16, 185, 129, 0.2)); + text-align: center; + font-size: 0.875rem; + line-height: 1.5; +} + +.release-bar__badge { + margin-right: 0.5rem; + padding: 0.125rem 0.5rem; + border-radius: 999px; + background: rgba(52, 211, 153, 0.2); + color: #a7f3d0; + font-size: 0.75rem; + font-weight: 600; + letter-spacing: 0.14em; + text-transform: uppercase; +} + +.release-bar__link { + white-space: nowrap; + color: #a7f3d0; +} + +.release-bar:hover .release-bar__link, +.release-bar:focus-visible .release-bar__link { + text-decoration: underline; + text-underline-offset: 4px; +} + +.visually-hidden { + position: absolute; + width: 1px; + height: 1px; + overflow: hidden; + clip-path: inset(50%); + white-space: nowrap; +} + +/* Long words in large headings otherwise overflow a 280px fold cover */ +.blog-hero__title, +.post-card__title, +.blog-post__title { + overflow-wrap: break-word; +} + .site-shell { min-height: 100vh; display: flex; @@ -153,9 +201,10 @@ a { padding: 0.75rem 1rem; border-bottom: 1px solid rgba(64, 64, 64, 0.9); background: rgb(23, 23, 27); - /* The header is sticky, so page scrolling never reveals a panel taller than a landscape phone */ - max-height: calc(100vh - 4rem); - max-height: calc(100dvh - 4rem); + /* Leave room for the header and the release bar above it (two lines on a phone); page + scrolling never reveals a panel taller than a landscape phone. */ + max-height: calc(100vh - 7.75rem); + max-height: calc(100dvh - 7.75rem); overflow-y: auto; overscroll-behavior: contain; } @@ -254,7 +303,7 @@ a { .blog-hero__title { margin: 0; - font-size: clamp(2.75rem, 6vw, 4.5rem); + font-size: clamp(2.25rem, 6vw, 4.5rem); line-height: 1.02; letter-spacing: -0.05em; } @@ -267,6 +316,24 @@ a { color: var(--muted); } +.blog-hero__cta { + display: inline-flex; + align-items: center; + gap: 0.5rem; + margin-top: 1.75rem; + padding: 0.8rem 1.5rem; + border-radius: 0.5rem; + background: #2563eb; + color: #fff; + font-weight: 600; + transition: background 180ms ease; +} + +.blog-hero__cta:hover, +.blog-hero__cta:focus-visible { + background: #1d4ed8; +} + .posts-group { margin-bottom: 3rem; } @@ -338,31 +405,13 @@ a { padding: 1.75rem; } -.post-card__media { - position: relative; - aspect-ratio: 16 / 9; - overflow: hidden; - border-bottom: 1px solid rgba(148, 163, 184, 0.14); - background: rgba(15, 23, 42, 0.8); -} - -.post-card__image { - display: block; - width: 100%; - height: 100%; - object-fit: cover; -} - -.post-card--featured .post-card__media { - aspect-ratio: 16 / 8; -} - .post-card--featured .post-card__body { padding: 2.3rem; } .post-card__header { display: flex; + flex-wrap: wrap; align-items: center; gap: 0.95rem; margin-bottom: 1.25rem; @@ -382,6 +431,20 @@ a { margin: 0; } +.post-card__ribbon { + margin-left: auto; + padding: 0.3rem 0.75rem; + border: 1px solid rgba(var(--accent-rgb), 0.45); + border-radius: 999px; + background: rgba(var(--accent-rgb), 0.14); + color: rgb(var(--accent-rgb)); + font-size: 0.72rem; + font-weight: 700; + letter-spacing: 0.12em; + text-transform: uppercase; + white-space: nowrap; +} + .post-card__source { font-size: 0.95rem; font-weight: 600; @@ -480,6 +543,11 @@ a { --accent-alt-rgb: 59, 130, 246; } +.post-card--release { + --accent-rgb: 52, 211, 153; + --accent-alt-rgb: 14, 165, 233; +} + .blog-post { max-width: 840px; } diff --git a/blogs/assets/images/posts/documentdb-for-vs-code-1-0/cluster-dashboard.png b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/cluster-dashboard.png new file mode 100644 index 0000000..6ab8fe9 Binary files /dev/null and b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/cluster-dashboard.png differ diff --git a/blogs/assets/images/posts/documentdb-for-vs-code-1-0/copy-and-paste.png b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/copy-and-paste.png new file mode 100644 index 0000000..fa920b9 Binary files /dev/null and b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/copy-and-paste.png differ diff --git a/blogs/assets/images/posts/documentdb-for-vs-code-1-0/documentdb-local.png b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/documentdb-local.png new file mode 100644 index 0000000..016a7fd Binary files /dev/null and b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/documentdb-local.png differ diff --git a/blogs/assets/images/posts/documentdb-for-vs-code-1-0/hero.png b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/hero.png new file mode 100644 index 0000000..424661a Binary files /dev/null and b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/hero.png differ diff --git a/blogs/assets/images/posts/documentdb-for-vs-code-1-0/query-insights-streaming.png b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/query-insights-streaming.png new file mode 100644 index 0000000..bbbb851 Binary files /dev/null and b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/query-insights-streaming.png differ diff --git a/blogs/assets/images/posts/documentdb-for-vs-code-1-0/road-to-1.0-illustrated.jpg b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/road-to-1.0-illustrated.jpg new file mode 100644 index 0000000..2ceeacb Binary files /dev/null and b/blogs/assets/images/posts/documentdb-for-vs-code-1-0/road-to-1.0-illustrated.jpg differ diff --git a/blogs/index.html b/blogs/index.html index 01d3efb..b90be6f 100644 --- a/blogs/index.html +++ b/blogs/index.html @@ -7,12 +7,17 @@ {% assign local_posts = site.posts | where_exp: "post", "post.featured != true" %} {% assign external_posts = site.data.posts | where_exp: "post", "post.featured != true" %} +{% assign announcement_href = site.release_announcement_url | relative_url %} +{% assign blog_href = '/' | relative_url %}
-

Community insights

-

Latest from our Blog

+

DocumentDB 1.0

+

DocumentDB 1.0 is here

- Insights, updates, and deep dives into the world of document databases and open-source innovation. + The release, its planned long-term support track, and the tools around it: the DocumentDB extension for Visual Studio Code 1.0 and the Kubernetes operator.

+ {% if announcement_href != blog_href %} + Read the announcement + {% endif %}
{% if featured_local_posts.size > 0 or featured_external_posts.size > 0 %} diff --git a/public/images/social-card-1.0.png b/public/images/social-card-1.0.png new file mode 100644 index 0000000..fee3458 Binary files /dev/null and b/public/images/social-card-1.0.png differ diff --git a/scripts/publish-installer.mjs b/scripts/publish-installer.mjs index cfaa351..6effc5d 100644 --- a/scripts/publish-installer.mjs +++ b/scripts/publish-installer.mjs @@ -3,10 +3,10 @@ import { mkdir, writeFile } from 'node:fs/promises'; import { resolve } from 'node:path'; import { pathToFileURL } from 'node:url'; -// v0.117-0 ships no installer; RC2's installs from the stable repository. -// Release assets can be replaced, so the digest is pinned too. +// v1.0-0 attaches the same bytes as v1.0-RC2. Release assets can be replaced, +// so the digest is pinned too. export const installerSource = { - release: 'v1.0-RC2', + release: 'v1.0-0', sha256: 'b9d16b3b86d3b1541e701be0ce38086dcb0bc904f761a36c7ede9fefe91d45f2', }; diff --git a/tests/containerCredentials.test.ts b/tests/containerCredentials.test.ts new file mode 100644 index 0000000..78f55cf --- /dev/null +++ b/tests/containerCredentials.test.ts @@ -0,0 +1,52 @@ +import { describe, expect, it } from 'vitest'; +import fs from 'node:fs'; +import path from 'node:path'; + +// A --password container argument is visible to anyone on the host (`ps`, +// `podman top`); the image reads USERNAME/PASSWORD from the environment instead. +const root = path.resolve(__dirname, '..'); + +function sources(): string[] { + const walk = (dir: string): string[] => + fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => { + const full = path.join(dir, entry.name); + if (entry.isDirectory()) return walk(full); + return /\.(tsx?|md)$/.test(entry.name) ? [full] : []; + }); + return [...walk(path.join(root, 'app')), ...walk(path.join(root, 'blogs', '_posts')), path.join(root, 'PACKAGE-INSTALL.md')]; +} + +// A run command plus its backslash-continued lines, in source or rendered form. +function runCommands(text: string): string[] { + const lines = text.split('\n'); + const commands: string[] = []; + lines.forEach((line, index) => { + if (!/\b(docker|podman) run\b/.test(line)) return; + const command = [line]; + for (let next = index; /\\\s*$/.test(lines[next]) && next + 1 < lines.length; next += 1) { + command.push(lines[next + 1]); + } + commands.push(command.join('\n')); + }); + return commands; +} + +describe('container credentials', () => { + it('finds the site run commands', () => { + const count = sources().flatMap((file) => runCommands(fs.readFileSync(file, 'utf8'))).length; + expect(count).toBeGreaterThan(10); + }); + + it.each(sources().map((file) => [path.relative(root, file), file]))('%s passes no credentials as container arguments', (_name, file) => { + for (const command of runCommands(fs.readFileSync(file, 'utf8'))) { + expect(command).not.toMatch(/--(password|username)\b/); + // docker run options must come before the image; after it they are container arguments. + const image = command.search(/ghcr\.io\/documentdb\/documentdb\/documentdb-local:/); + for (const option of ['-e USERNAME=', '-e PASSWORD=']) { + if (image >= 0 && command.includes(option)) { + expect(command.indexOf(option)).toBeLessThan(image); + } + } + } + }); +}); diff --git a/tests/fixtures/documentdb-local/index.md b/tests/fixtures/documentdb-local/index.md new file mode 100644 index 0000000..50ac874 --- /dev/null +++ b/tests/fixtures/documentdb-local/index.md @@ -0,0 +1,12 @@ +--- +title: DocumentDB Local +--- +# DocumentDB Local + +## Built-in sample data + +Pass `--init-data true` to load the sample on a new volume. + +## Feature support + +Source feature support. diff --git a/tests/installSelection.test.ts b/tests/installSelection.test.ts index 50326a1..4ede569 100644 --- a/tests/installSelection.test.ts +++ b/tests/installSelection.test.ts @@ -116,16 +116,16 @@ describe("install selection links", () => { describe("published package availability", () => { const assetNames = [ ...["documentdb-18", "documentdb-common", "documentdb-postgresql-tools"].flatMap((name) => [ - `ubuntu24.04-${name}_0.117.0_all.deb`, - `${name}-0.117.0-1.noarch.rpm`, + `ubuntu24.04-${name}_1.0.0_all.deb`, + `${name}-1.0.0-1.noarch.rpm`, ]), ...["amd64", "arm64"].flatMap((arch) => [ - `ubuntu24.04-documentdb-gateway_0.117.0_${arch}.deb`, - `ubuntu24.04-postgresql-18-documentdb_0.117-0_${arch}.deb`, + `ubuntu24.04-documentdb-gateway_1.0.0_${arch}.deb`, + `ubuntu24.04-postgresql-18-documentdb_1.0-0_${arch}.deb`, ]), ...["x86_64", "aarch64"].flatMap((arch) => [ - `documentdb-gateway-0.117.0-1.el9.${arch}.rpm`, - `rhel9-postgresql18-documentdb-0.117.0-1.el9.${arch}.rpm`, + `documentdb-gateway-1.0.0-1.el9.${arch}.rpm`, + `rhel9-postgresql18-documentdb-1.0.0-1.el9.${arch}.rpm`, ]), ]; const release = { ...FALLBACK_RELEASE, assetNames }; @@ -151,7 +151,7 @@ describe("published package availability", () => { expect(releaseHasPackages(partial, defaultInstallSelection.packages)).toBe(false); }); - it.each([null, {}, { tag_name: "v0.117-0", assets: [] }, { tag_name: "../other", assets: [] }])( + it.each([null, {}, { tag_name: "v1.0-0", assets: [] }, { tag_name: "../other", assets: [] }])( "surfaces malformed or incomplete metadata instead of inventing current versions", (payload) => { expect(() => parseReleaseInfo(payload)).toThrow(); diff --git a/tests/markdownBasePath.test.tsx b/tests/markdownBasePath.test.tsx new file mode 100644 index 0000000..3520976 --- /dev/null +++ b/tests/markdownBasePath.test.tsx @@ -0,0 +1,34 @@ +import { afterEach, describe, expect, it, vi } from 'vitest'; +import { renderToStaticMarkup } from 'react-dom/server'; +import { createElement } from 'react'; + +async function render(content: string, basePath?: string) { + vi.resetModules(); + // Pin both variables so an ambient NEXT_BASE_PATH can't leak into the no-base case. + vi.stubEnv('NEXT_PUBLIC_BASE_PATH', basePath ?? ''); + vi.stubEnv('NEXT_BASE_PATH', ''); + const Markdown = (await import('../app/components/Markdown')).default; + return renderToStaticMarkup(createElement(Markdown, { content, sourcePath: '/docs/getting-started/index.md' })); +} + +afterEach(() => { + vi.unstubAllEnvs(); + vi.resetModules(); +}); + +describe('Markdown root-relative links', () => { + it('prefixes the base path on a project-page deployment', async () => { + const html = await render('[a](/docs/documentdb-local#usage-telemetry) [b](/blogs/) [c](https://x.test/y) [d](#here) [e](//cdn.test/z)', '/documentdb.github.io'); + expect(html).toContain('href="/documentdb.github.io/docs/documentdb-local#usage-telemetry"'); + expect(html).toContain('href="/documentdb.github.io/blogs/"'); + expect(html).toContain('href="https://x.test/y"'); + expect(html).toContain('href="#here"'); + expect(html).toContain('href="//cdn.test/z"'); + }); + + it('leaves root paths and protocol-relative URLs alone without a base path', async () => { + const html = await render('[a](/docs/x) [b](//cdn.test/z)'); + expect(html).toContain('href="/docs/x"'); + expect(html).toContain('href="//cdn.test/z"'); + }); +}); diff --git a/tests/markdownLinks.test.ts b/tests/markdownLinks.test.ts index b94cec9..bbe6c28 100644 --- a/tests/markdownLinks.test.ts +++ b/tests/markdownLinks.test.ts @@ -185,8 +185,20 @@ describe('client-reachable modules and the private base path', () => { const code = source.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\//g, ''); expect(code).not.toContain('NEXT_BASE_PATH'); - expect(code).not.toContain('sitePath'); - expect(code).not.toContain('withBasePath'); }, ); + + // The resolver must give the same route with or without a base path; the + // renderer may prefix through withBasePath, which reads the public copy. + it('app/lib/markdownLinks.ts does not import sitePath', async () => { + const { readFile } = await import('node:fs/promises'); + const { fileURLToPath } = await import('node:url'); + const source = await readFile( + fileURLToPath(new URL('../app/lib/markdownLinks.ts', import.meta.url)), + 'utf8', + ); + const code = source.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\//g, ''); + expect(code).not.toContain('sitePath'); + expect(code).not.toContain('withBasePath'); + }); }); diff --git a/tests/packageArticles.test.ts b/tests/packageArticles.test.ts index 1f96eab..6f1bc85 100644 --- a/tests/packageArticles.test.ts +++ b/tests/packageArticles.test.ts @@ -51,10 +51,11 @@ describe('Linux package articles', () => { expect(blocks).toContain(buildRpmInstallCommand('rhel9', 'auto', '18')); expect(blocks).toContain(buildSetupCommand('18')); expect(linuxPackagesGuideContent).toContain('amd64 or arm64'); - expect(linuxPackagesGuideContent.indexOf('fresh installation only')).toBeLessThan( + // Existing installs must see the upgrade route before the first install command. + expect(linuxPackagesGuideContent.indexOf('(/docs/linux-packages#upgrading)')).toBeGreaterThan(-1); + expect(linuxPackagesGuideContent.indexOf('(/docs/linux-packages#upgrading)')).toBeLessThan( linuxPackagesGuideContent.indexOf('```bash'), ); - expect(linuxPackagesGuideContent).toContain('not in-place package upgrades'); expect(linuxPackagesGuideContent).toContain( 'Removing packages preserves database files', ); @@ -91,6 +92,8 @@ describe('Linux package articles', () => { expect(article.content).toContain('acknowledged: true'); expect(article.content).toContain('Run this shell example on the same host as DocumentDB'); expect(article.content).toContain('## Architecture Components'); + expect(article.content).toContain('four primary components'); + expect(article.content).toContain('**pg_documentdb_extended_rum**'); expect(article.content).toContain('## Common Use Cases'); expect(article.content).toContain('## Community and Support'); const packageIndex = article.navigation.findIndex((item) => @@ -117,9 +120,9 @@ describe('Linux package articles', () => { ); expect(source).toContain('-p 127.0.0.1:10260:10260'); expect(source).not.toContain('-p 10260:10260'); - expect(source).toContain("--username ''"); - expect(source).toContain("--password ''"); - expect(source).toContain('Pre-GA, fresh installation only'); + expect(source).toContain("-e USERNAME=''"); + expect(source).toContain("-e PASSWORD=''"); + expect(source).not.toContain('Pre-GA'); }); it('offers both server methods before client-specific setup or optional Docker commands', () => { @@ -283,25 +286,25 @@ describe('Linux package articles', () => { expect(new Set(tags)).toEqual(new Set([FALLBACK_RELEASE.tagName])); }); - it('serves the stable installer and selects RC2 only with --version', () => { + it('serves the stable installer without a pinned or RC version', () => { expect(linuxPackagesGuideContent).toContain('https://documentdb.io/install.sh'); - expect(linuxPackagesGuideContent).toContain('installs v0.117-0 from the package repository'); - expect(linuxPackagesGuideContent).toContain('sh documentdb-install.sh --version v1.0-RC2'); - expect(linuxPackagesGuideContent).toContain("doesn't use the package repository"); - expect(linuxPackagesGuideContent).toContain('DOCUMENTDB_USAGE_TELEMETRY=false'); + expect(linuxPackagesGuideContent).toContain('installs the current release (v1.0-0) from the package repository'); + // install.sh rejects --version v1.0-0, and RCs are retired at GA. + expect(linuxPackagesGuideContent).not.toContain('--version v1.0'); + expect(linuxPackagesGuideContent).not.toMatch(/RC2|release-candidate/); }); it('uses the current release package guide and artifact version', () => { const offlineGuide = getArticleByPath('linux-packages', ['offline']); expect(linuxPackagesGuideContent).toContain( - 'documentdb/blob/v0.117-0/packaging/README.md', + 'documentdb/blob/v1.0-0/packaging/README.md', ); expect(linuxPackagesGuideContent).toContain( '`--load-sample-data` to the setup command to seed the `StoreData` database', ); expect(offlineGuide?.content).toContain( - 'ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb', + 'ubuntu24.04-postgresql-18-documentdb_1.0-0_amd64.deb', ); expect(offlineGuide?.content).toContain( 'pass the five packages for the selected PostgreSQL major', @@ -386,15 +389,8 @@ describe('Linux package articles', () => { 'utf8', ); - expect(source).toContain( - '41,505 store documents and 2 rating documents', - ); - expect(source).toContain( - 'documentdb-local:pg18-0.117.0', - ); - expect(source).toContain( - 'Currently identical to \\`pg17-0.117.0\\`', - ); + // The DocumentDB Local page comes from the docs repo; the site adds no image or sample section. + expect(source).not.toContain('Currently identical to'); expect(source).not.toContain( '5 users, 5 products, 4 orders, and 2', ); @@ -425,8 +421,8 @@ describe('Linux package articles', () => { for (const block of dockerBlocks) { expect(block, slug).toContain('-p 127.0.0.1:10260:10260'); expect(block, slug).not.toContain('-p 10260:10260'); - expect(block, slug).not.toContain('--username '); - expect(block, slug).not.toContain('--password '); + expect(block, slug).not.toContain('--username'); + expect(block, slug).not.toContain('--password'); } } @@ -442,25 +438,19 @@ describe('Linux package articles', () => { ); expect(articleSource).toContain( - 'docker run -dt -p 127.0.0.1:10260:10260 --name documentdb', - ); - expect(articleSource).toContain( - " --username '' --password '' --init-data true", + " ghcr.io/documentdb/documentdb/documentdb-local:latest \\\\\n --init-data true", ); expect(articleSource).toContain( ' -p 127.0.0.1:10260:10260 \\\\', ); - expect(articleSource).toContain( - ' -v /path/to/init/scripts:/init_doc_db.d \\\\', - ); expect(packagePageSource).toContain( ' -p 127.0.0.1:10260:10260 \\\\', ); expect(packagePageSource).toContain( - " --username '' \\\\", + " -e USERNAME='' \\\\", ); expect(packagePageSource).toContain( - " --password ''", + " -e PASSWORD='' \\\\", ); }); @@ -555,3 +545,65 @@ describe('Linux package articles', () => { expect(source).not.toContain('and the gateway are'); }); }); + +describe('manual extension upgrade SQL', () => { + it.each([ + ['the operations guide', () => linuxPackagesOperationsContent], + ['PACKAGE-INSTALL.md', () => fs.readFileSync(fileURLToPath(new URL('../PACKAGE-INSTALL.md', import.meta.url)), 'utf8')], + ])('restarts PostgreSQL, updates every extension in one transaction and gates the gateway in %s', (_name, read) => { + const text = read(); + const command = text.match(/sudo systemctl restart documentdb-postgresql@18\.service &&\nsudo -u documentdb-local psql[\s\S]*?documentdb-gateway-local@18\.service/)?.[0]; + expect(command).toBeDefined(); + expect(command).toContain('-X -1 -v ON_ERROR_STOP=1'); + // A later -v ON_ERROR_STOP or ON_ERROR_ROLLBACK would undo the error gate. + expect(command!.match(/ON_ERROR_STOP/g)).toHaveLength(1); + expect(command).not.toContain('ON_ERROR_ROLLBACK'); + expect(command).toContain('-p 9718 -d postgres \\\n'); + // Exactly the four statements: no COMMIT/BEGIN of its own to split the transaction. + expect(command!.match(/ -c '/g)).toHaveLength(4); + expect(command).not.toMatch(/BEGIN|COMMIT|ROLLBACK/); + const order = [ + "-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;' &&\nsudo systemctl start", + ].map((part) => command!.indexOf(part)); + expect(order.every((index) => index >= 0)).toBe(true); + expect([...order].sort((a, b) => a - b)).toEqual(order); + // The preload check comes before the transaction, which can't detect a missing preload. + expect(text.indexOf('SHOW shared_preload_libraries;')).toBeGreaterThan(-1); + expect(text.indexOf('SHOW shared_preload_libraries;')).toBeLessThan(text.indexOf(command!)); + // The old separate-statement form committed each ALTER on its own. + expect(text).not.toMatch(/^ALTER EXTENSION documentdb_core UPDATE;$/m); + expect(text).toMatch(/only in\s+the `postgres` database/); + // Restarting the whole target would start the gateway before setup updates the extensions. + expect(text).toMatch(/restart documentdb-postgresql@18\.service &&\nsudo documentdb-setup/); + expect(text).not.toMatch(/restart documentdb-local@18\.target &&\nsudo documentdb-setup/); + }); +}); + +describe('docs-owned article normalization', () => { + beforeEach(() => { + const fixturePaths = new Map([ + [path.join(process.cwd(), 'articles', 'documentdb-local', 'index.md'), + fileURLToPath(new URL('./fixtures/documentdb-local/index.md', import.meta.url))], + ]); + const existsSync = fs.existsSync; + const readFileSync = fs.readFileSync; + vi.spyOn(fs, 'existsSync').mockImplementation((file) => existsSync(fixturePaths.get(file.toString()) ?? file)); + vi.spyOn(fs, 'readFileSync').mockImplementation((file, options) => + readFileSync(fixturePaths.get(file.toString()) ?? file, options), + ); + }); + + afterEach(() => { + vi.restoreAllMocks(); + }); + + it('serves the DocumentDB Local page as the docs repo wrote it', () => { + const article = getArticleByPath('documentdb-local', []); + expect(article?.content).toContain('## Built-in sample data'); + expect(article?.content).not.toMatch(/## (Container image tags|Data initialization)/); + expect(article?.content).not.toContain('on a fresh volume'); + }); +}); diff --git a/tests/packageInstall.test.ts b/tests/packageInstall.test.ts index fb0fb85..7f20d37 100644 --- a/tests/packageInstall.test.ts +++ b/tests/packageInstall.test.ts @@ -1,3 +1,7 @@ +import { execFileSync } from 'node:child_process'; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; import { describe, expect, it } from 'vitest'; import { aptServesFullStack, @@ -75,33 +79,33 @@ describe('package metadata', () => { }); describe('release metadata', () => { - it('uses v0.117-0 for the first paint and feed fallback', () => { + it('uses v1.0-0 for the first paint and feed fallback', () => { expect(FALLBACK_RELEASE).toMatchObject({ - tagName: 'v0.117-0', - aptVersion: '0.117-0', - rpmVersion: '0.117.0-1.el9', - metaVersion: '0.117.0', - metaRpmVersion: '0.117.0-1', - releaseUrl: 'https://github.com/documentdb/documentdb/releases/tag/v0.117-0', + tagName: 'v1.0-0', + aptVersion: '1.0-0', + rpmVersion: '1.0.0-1.el9', + metaVersion: '1.0.0', + metaRpmVersion: '1.0.0-1', + releaseUrl: 'https://github.com/documentdb/documentdb/releases/tag/v1.0-0', }); }); - it('derives v0.117 package versions from the published asset shapes', () => { + it('derives v1.0 package versions from the published asset shapes', () => { expect(parseReleaseInfo({ - tag_name: 'v0.117-0', - html_url: 'https://github.com/documentdb/documentdb/releases/tag/v0.117-0', + tag_name: 'v1.0-0', + html_url: 'https://github.com/documentdb/documentdb/releases/tag/v1.0-0', assets: [ - { name: 'ubuntu24.04-documentdb_0.117.0_all.deb' }, - { name: 'ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb' }, - { name: 'documentdb-0.117.0-1.noarch.rpm' }, - { name: 'rhel9-postgresql18-documentdb-0.117.0-1.el9.x86_64.rpm' }, + { name: 'ubuntu24.04-documentdb_1.0.0_all.deb' }, + { name: 'ubuntu24.04-postgresql-18-documentdb_1.0-0_amd64.deb' }, + { name: 'documentdb-1.0.0-1.noarch.rpm' }, + { name: 'rhel9-postgresql18-documentdb-1.0.0-1.el9.x86_64.rpm' }, ], })).toMatchObject({ - tagName: 'v0.117-0', - aptVersion: '0.117-0', - rpmVersion: '0.117.0-1.el9', - metaVersion: '0.117.0', - metaRpmVersion: '0.117.0-1', + tagName: 'v1.0-0', + aptVersion: '1.0-0', + rpmVersion: '1.0.0-1.el9', + metaVersion: '1.0.0', + metaRpmVersion: '1.0.0-1', }); }); }); @@ -214,6 +218,42 @@ describe('buildRpmInstallCommand', () => { expect(command).not.toContain('codeready-builder-for-rhel'); }); + it('switches PGDG to its major-only path on CentOS Stream only', () => { + const lines = buildRpmInstallCommand('rocky9', 'x86_64', '18') + .split('\n') + .filter((l) => l.startsWith('if (. /etc/os-release')); + // Once before the first dnf call (a repo left by an earlier attempt) and once after PGDG is added. + expect(lines).toHaveLength(2); + expect(lines[0]).toBe(lines[1]); + expect(buildRpmInstallCommand('rhel9', 'x86_64', '18')).not.toContain('pgdg-redhat-all.repo'); + const baseurl = + 'baseurl=https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-$releasever_major.$releasever_minor-$basearch\n'; + const run = (osRelease: string, withRepo = true) => { + const dir = mkdtempSync(join(tmpdir(), 'pgdg-')); + try { + writeFileSync(join(dir, 'os-release'), osRelease); + if (withRepo) writeFileSync(join(dir, 'pgdg.repo'), baseurl); + // Paths go in as positional arguments so a TMPDIR with spaces stays one word. + const script = lines[0] + .replaceAll('/etc/os-release', '"$1"') + .replaceAll('/etc/yum.repos.d/pgdg-redhat-all.repo', '"$2"') + .replace('sudo sed -i ', 'sed -i.bak ') + .replace(/ && \\$/, ''); + execFileSync('sh', ['-c', script, 'sh', join(dir, 'os-release'), join(dir, 'pgdg.repo')]); + return withRepo ? readFileSync(join(dir, 'pgdg.repo'), 'utf8') : ''; + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }; + const fixed = '/redhat/rhel-$releasever_major-$basearch'; + expect(run('ID=centos\n')).toContain(fixed); + expect(run('ID="centos"\n')).toContain(fixed); + expect(run("ID='centos'\n")).toContain(fixed); + expect(run('ID="rocky"\n')).toBe(baseurl); + expect(run('ID="centos\n')).toBe(baseurl); + expect(run('ID="centos"\n', false)).toBe(''); + }); + it('uses subscription-manager for registered RHEL', () => { const command = buildRpmInstallCommand('rhel9', 'aarch64', '18'); expect(command).toContain( diff --git a/tests/quickStart.test.ts b/tests/quickStart.test.ts index b96d35d..1580d96 100644 --- a/tests/quickStart.test.ts +++ b/tests/quickStart.test.ts @@ -70,8 +70,9 @@ describe('homepage local quick start', () => { const command = panel('command'); expect(command).toContain('-p 127.0.0.1:10260:10260'); expect(command).not.toContain('-p 10260:10260 '); - expect(command).toContain("--username '<YOUR_USERNAME>'"); - expect(command).toContain("--password '<YOUR_PASSWORD>'"); + expect(command).toContain("-e USERNAME='<YOUR_USERNAME>'"); + expect(command).toContain("-e PASSWORD='<YOUR_PASSWORD>'"); + expect(command).not.toContain('--password'); expect(command).toContain('ghcr.io/documentdb/documentdb/documentdb-local:latest'); expect(command).not.toContain('--init-data'); }); diff --git a/tests/sitePath.test.ts b/tests/sitePath.test.ts index dd25027..a557820 100644 --- a/tests/sitePath.test.ts +++ b/tests/sitePath.test.ts @@ -4,10 +4,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; // it after stubbing. async function importWithEnv(env: Record) { vi.resetModules(); - for (const [key, value] of Object.entries(env)) { - if (value !== undefined) { - vi.stubEnv(key, value); - } + // Pin both variables so the invoking shell's base path can't leak in. + for (const key of ['NEXT_PUBLIC_BASE_PATH', 'NEXT_BASE_PATH']) { + vi.stubEnv(key, env[key] ?? ''); } return (await import('../app/services/sitePath')).withBasePath; }