Skip to content

Add a guided Linux packages install flow, keeping Docker the default #180

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
GuanzhouSong wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add a guided Linux packages install flow, keeping Docker the default #180

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f55f788
Add a guided Linux packages install flow, keeping Docker the default
guanzhousongmicrosoft Sep 23, 2026
c14d9c4
Keep install choices across methods and stop hiding commands on metad…
guanzhousongmicrosoft Sep 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 24 additions & 7 deletions app/components/CommandSnippet.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,31 @@
"use client";

import { useState } from "react";
import { useEffect, useRef, useState } from "react";

type CommandSnippetProps = {
command: string;
label?: string;
};

export default function CommandSnippet({ command, label = "Command" }: CommandSnippetProps) {
const [copied, setCopied] = useState(false);
const [feedback, setFeedback] = useState<{ command: string; error: boolean } | null>(null);
const timeout = useRef<ReturnType<typeof setTimeout> | null>(null);

useEffect(() => () => {
if (timeout.current !== null) clearTimeout(timeout.current);
}, []);

const copyCommand = async () => {
await navigator.clipboard.writeText(command);
setCopied(true);
window.setTimeout(() => setCopied(false), 1500);
if (timeout.current !== null) clearTimeout(timeout.current);
try {
await navigator.clipboard.writeText(command);
setFeedback({ command, error: false });
timeout.current = setTimeout(() => setFeedback(null), 2000);
} catch {
setFeedback({ command, error: true });
}
};
const currentFeedback = feedback?.command === command ? feedback : null;

return (
<div className="w-full max-w-full overflow-hidden rounded-lg border border-neutral-700 bg-black">
Expand All @@ -25,11 +36,17 @@ export default function CommandSnippet({ command, label = "Command" }: CommandSn
<button
type="button"
onClick={copyCommand}
className="rounded border border-neutral-600 px-2 py-1 text-xs font-medium text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
aria-label={`Copy ${label}`}
className="rounded border border-neutral-600 px-2 py-1 text-xs font-medium text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-400"
>
{copied ? "Copied" : "Copy"}
{currentFeedback && !currentFeedback.error ? "Copied" : "Copy"}
</button>
</div>
<p role="status" className={currentFeedback?.error ? "px-3 pb-3 text-sm text-amber-200" : "sr-only"}>
{currentFeedback?.error
? "Could not copy. Select the command text and copy it manually."
: currentFeedback ? `${label} copied. Run it in your terminal.` : ""}
</p>
<div className="w-full max-w-full overflow-x-auto overscroll-x-contain px-3 py-3 [scrollbar-gutter:stable]">
<pre className="m-0 w-full whitespace-pre text-xs leading-relaxed text-green-400">
<code>{command}</code>
Expand Down
6 changes: 3 additions & 3 deletions app/components/Navbar.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ const navItems: NavItem[] = [
},
{ label: "Docs", href: "/docs", kind: "link" },
{ label: "AI", href: "/ai", kind: "link" },
{ label: "Download", href: "/packages", kind: "link" },
{ label: "Install & Download", href: "/packages", kind: "link" },
{ label: "K8s Operator", href: "/kubernetes-operator", kind: "link" },
{ label: "Blogs", href: withBasePath("/blogs/"), kind: "anchor" },
{ label: "Samples", href: "/samples", kind: "link" },
Expand Down Expand Up @@ -117,7 +117,7 @@ export default function Navbar() {
{navItems.map((item) =>
renderNavItem(
item,
"flex items-center gap-2 text-gray-300 transition-colors duration-200 font-medium hover:text-blue-400",
"flex items-center gap-2 text-gray-300 transition-colors duration-200 font-medium hover:text-blue-400 focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-blue-400",
),
)}
</div>
Expand Down Expand Up @@ -148,7 +148,7 @@ export default function Navbar() {
{navItems.map((item) =>
renderNavItem(
item,
"flex items-center gap-3 rounded-md px-3 py-2.5 text-sm font-medium text-gray-300 transition-colors duration-200 hover:bg-neutral-800 hover:text-white",
"flex items-center gap-3 rounded-md px-3 py-2.5 text-sm font-medium text-gray-300 transition-colors duration-200 hover:bg-neutral-800 hover:text-white focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-400",
closeMenu,
),
)}
Expand Down
68 changes: 41 additions & 27 deletions app/docs/[section]/[[...slug]]/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,13 @@ import ComingSoon from "../../../components/ComingSoon";
import CommandSnippet from "../../../components/CommandSnippet";
import Markdown from "../../../components/Markdown";
import MovedNotice from "../../../components/MovedNotice";
import { aptTargetLabels } from "../../../lib/packageInstall";

const dockerQuickRunCommand = `docker run -dt --name documentdb \\
-p 10260:10260 \\
-p 127.0.0.1:10260:10260 \\
ghcr.io/documentdb/documentdb/documentdb-local:latest \\
--username <YOUR_USERNAME> \\
--password <YOUR_PASSWORD>`;
--username '<YOUR_USERNAME>' \\
--password '<YOUR_PASSWORD>'`;

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";
Expand Down Expand Up @@ -241,11 +242,11 @@ export default async function ArticlePage({ params }: PageProps) {
Recommended flow
</p>
<h2 className="mt-2 text-2xl font-semibold text-white">
Install and verify DocumentDB
Choose an environment, then run your first query
</h2>
<p className="mt-2 max-w-3xl text-sm leading-6 text-gray-300">
Choose one install path first. After DocumentDB is running, verify the
connection with mongosh before moving to a driver quick start.
Install with Docker or Linux packages once. Create a working instance,
then insert and read a document using a shell, driver, or editor.
</p>
<div className="mt-5 rounded-xl border border-neutral-800 bg-neutral-950/40 p-4">
<div className="mb-4 flex items-start gap-3">
Expand All @@ -257,22 +258,28 @@ export default async function ArticlePage({ params }: PageProps) {
Choose an install path
</p>
<p className="mt-1 text-sm text-gray-400">
Use Docker for the fastest local setup, or Linux packages for a
persistent host installation.
Start with Docker on Linux, macOS, or Windows. Use Linux packages
when you need a host installation.
</p>
</div>
</div>
<div className="grid gap-4 lg:grid-cols-2">
<div className="rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
<p className="text-sm font-semibold text-white">
Run locally with Docker
Docker: recommended for evaluation and development
</p>
<p className="mt-2 text-sm text-gray-400">
Best for evaluation, local development, and quick testing.
With Docker installed, run a local instance on Linux, macOS, or
Windows. Replace the credential placeholders before running.
The port stays on loopback.
</p>
<div className="mt-4">
<CommandSnippet command={dockerQuickRunCommand} label="Docker" />
<CommandSnippet command={dockerQuickRunCommand} label="Start Docker" />
</div>
<p className="mt-4 text-sm text-gray-400">
Wait for the readiness banner in{" "}
<code>docker logs documentdb</code> before connecting.
</p>
<div className="mt-4">
<Link
href="/docs/getting-started/docker"
Expand All @@ -284,24 +291,32 @@ export default async function ArticlePage({ params }: PageProps) {
</div>
<div className="rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
<p className="text-sm font-semibold text-white">
Install from Linux packages
Linux packages
</p>
<p className="mt-2 text-sm text-gray-400">
Use the repository-backed package flow when you want a persistent
server install. Generate the exact apt or rpm command with the{" "}
<Link href="/packages" className={primerSecondaryLinkClass}>
Package Finder
</Link>
.
For environments without Docker, or when you need control over
PostgreSQL, topology, services, and configuration. Install with
apt or dnf on {aptTargetLabels.ubuntu24} or EL9, then run the setup wizard.
</p>
<p className="mt-2 text-sm text-gray-400">
Pre-GA, fresh installation only; in-place upgrades from earlier
releases are not supported.
</p>
<div className="mt-4">
<Link
href="/docs/getting-started/packages"
className={primerPrimaryLinkClass}
href="/packages?method=packages"
className={primerSecondaryLinkClass}
>
Linux Packages Quick Start
Linux packages installation
</Link>
</div>
<p className="mt-3 text-sm text-gray-400">
For the full walkthrough, see the{" "}
<Link href="/docs/getting-started/packages" className={primerSecondaryLinkClass}>
Linux Packages Quick Start
</Link>
.
</p>
</div>
</div>
</div>
Expand All @@ -312,14 +327,13 @@ export default async function ArticlePage({ params }: PageProps) {
</span>
<div className="min-w-0">
<p className="text-sm font-semibold text-white">
Recommended: verify with mongosh
Insert and read your first document
</p>
<p className="mt-1 text-sm text-gray-400">
This is the fastest shared validation path after either install
option because it confirms authentication, TLS, and a working
endpoint before you add editor or driver setup. If you already
know your target workflow, you can skip this and continue directly
with VS Code or a driver quick start.
Install mongosh separately for the shell walkthrough below, or
use your preferred language or editor. Each guide connects to
the instance you already created and verifies an insert and read.
Sample data is optional.
</p>
<div className="mt-4 flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center sm:gap-4">
<Link
Expand Down
Loading
Loading