docs: Windows PowerShell compatibility improvements across Quickstart, Install, Playground, and Dev Environment guides

[jaiswal-naman]

docs: Windows PowerShell compatibility improvements across Quickstart, Install, Playground, and Dev Environment guides

Closes #357

Why this PR

This PR resolves Windows-specific documentation gaps that make the current guides difficult or impossible to follow in PowerShell.

Before these changes, key commands were Unix-only (curl | docker compose, sh -c, ./build.sh, lsof, $(pwd) paths, \ line continuation). As a result, Windows users either hit command errors directly or had to infer unsupported workarounds.

This PR adds explicit Windows PowerShell paths while preserving all existing macOS/Linux instructions.

---

Scope

Files updated

• docs/getting-started/quickstart.mdx
• docs/install/olake-ui/index.mdx
• docs/install/docker-cli.mdx
• docs/getting-started/playground.mdx
• docs/community/setting-up-a-dev-env.mdx

Change size (from previous validated patch set)

• docs/community/setting-up-a-dev-env.mdx: +246 / -3
• docs/getting-started/playground.mdx: +258 / -48
• docs/getting-started/quickstart.mdx: +77 / -18
• docs/install/docker-cli.mdx: +22 / -0
• docs/install/olake-ui/index.mdx: +159 / -26

---

Detailed changes (with before/after)

1) docs/getting-started/quickstart.mdx

What changed

• Added a Docker readiness tip (docker info) in prerequisites.
• Added Windows PowerShell subtabs under both setup modes:
  • New (docker-compose-v1.yml)
  • Legacy (docker-compose.yml)
• Added Windows PowerShell subtabs in Updating OLake UI with down + pull + up -d flow.

Why

The original Unix pipeline pattern is not reliable for PowerShell users:

Before (Unix-only):

curl -sSL https://raw.githubusercontent.com/datazip-inc/olake-ui/master/docker-compose-v1.yml | docker compose -f - up -d

After (Windows tab added):

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/datazip-inc/olake-ui/master/docker-compose-v1.yml" -OutFile "docker-compose-v1.yml"
docker compose -f docker-compose-v1.yml up -d

Screenshot placeholders

• Quickstart prerequisites tip (docker info)
• New mode → Windows subtab
• Legacy mode → Windows subtab
• Updating section → Windows flow (down/pull/up)

---

2) docs/install/olake-ui/index.mdx

What changed

• Added prerequisites tip mentioning Docker verification and Windows WSL2 readiness context.
• Added Windows subtabs for:
  • Quick Start (New + Legacy)
  • Updating (New + Legacy)
  • Upgrade path (Legacy → New)
• Expanded Port Conflicts troubleshooting with practical Windows workflow and examples.

Why

This page is often the first install entry point. Without PowerShell-native commands, Windows users encounter immediate friction.

Before/after highlight: Port conflict guidance

Before:

• Minimal platform guidance.
• Placeholder PID format caused confusion when copied literally.

After:

• Explicit Windows command:

netstat -ano | findstr :8000

• Follow-up process lookup example:

Get-Process -Id 4521

• Clarifies two resolution paths:
  1. Stop conflicting process
  2. Change host port mapping in compose file and restart

Screenshot placeholders

• Quick Start New → Windows tab
• Quick Start Legacy → Windows tab
• Updating New/Legacy → Windows tabs
• Upgrade Legacy→New Windows tabs
• Port Conflicts expanded section (Windows commands + examples)

---

3) docs/install/docker-cli.mdx

What changed

• Added Windows Users note clarifying PowerShell line continuation differences.

Why

PowerShell does not use \ as a line continuation character. Many users copy multi-line examples as-is and hit failures.

Before/after highlight

Before (Unix-style multiline only):

docker run --pull=always \
  -v "/path/to/config:/mnt/config" \
  olakego/source-postgres:latest \
  discover \
  --config /mnt/config/source.json

After (Windows equivalent shown):

docker run --pull=always `
  -v "C:\path\to\config:/mnt/config" `
  olakego/source-postgres:latest `
  discover `
  --config /mnt/config/source.json

Screenshot placeholders

• Docker CLI note showing \ vs backtick
• Side-by-side Linux/macOS and Windows examples

---

4) docs/getting-started/playground.mdx

What changed

• Added explicit Step 2: Clone the OLake repo and start services for all engines.
• Added note clarifying query-engine compose files live in the olake repo (not olake-ui).
• Added Windows Set-Location equivalents.
• Added Windows tabs in setup and cleanup paths.

Why

This was a functional documentation gap: users were instructed to navigate into engine directories without first cloning the repository that contains those directories.

Before/after highlight

Before:

• Navigate directly to engine example path (assumes repo already exists).

After:

git clone https://github.com/datazip-inc/olake.git
cd olake/examples/trino-tablurarest-minio-mysql
docker compose up -d

Windows equivalent added:

git clone https://github.com/datazip-inc/olake.git
Set-Location olake/examples/trino-tablurarest-minio-mysql
docker compose up -d

Important naming correctness

Directory names follow upstream exactly:

• Trino: trino-tablurarest-minio-mysql
• Presto: presto-tabularest-minio-mysql
• Spark: spark-tablurarest-minio-mysql

(Presto spelling differs from Trino/Spark and is intentionally preserved.)

Screenshot placeholders

• Trino Step 2 with clone + path
• Presto Step 2 with presto-tabularest-...
• Spark Step 2 with spark-tablurarest-...
• Windows Set-Location examples

---

5) docs/community/setting-up-a-dev-env.mdx

What changed

Comprehensive Windows support added across the full developer journey:

• Prerequisites: Windows tabs for Java, Go, Node.js, Docker Desktop, Maven
• Added winget install commands + verification commands
• Added Java JAVA_HOME caution block
• Added Docker Desktop WSL2 requirement note (wsl --install)
• Added Windows path for source/destination setup
• Added HTTPS clone path for Windows users
• Replaced Unix-only execution flow with PowerShell-native go run commands for:
  • discover
  • full-refresh sync
  • incremental sync
  • CDC sync
  • demo step syncs
• Added Windows tips for port checks (netstat -ano | findstr :8888)
• Added Windows path examples in VS Code debug config section
• Added Windows steps for Iceberg JAR build/copy flow

Why

The original flow assumed Bash availability and Unix utilities. This prevented clean execution on Windows for core developer tasks.

Before/after highlights

Before (Unix-only setup shell):

sh -c 'curl ... && curl ... && docker compose ...'

After (PowerShell tab):

Invoke-WebRequest -Uri "<source-compose-url>" -OutFile "docker-compose.source.yml"
Invoke-WebRequest -Uri "<dest-compose-url>" -OutFile "docker-compose.destination.yml"
docker compose -f docker-compose.source.yml --profile postgres -f docker-compose.destination.yml up -d

Before (Unix-only execution):

./build.sh driver-postgres discover --config $(pwd)/source.json

After (Windows native execution):

go run ./drivers/postgres/main.go discover --config "$PWD\source.json"

Screenshot placeholders

• Java/Go/Node/Docker/Maven Windows tabs
• Docker WSL2 callout
• Source/Destination setup PowerShell tab
• Discover/Sync Windows commands (go run)
• Iceberg JAR build/copy Windows tabs
• Port 8888 Windows tip
• VS Code debug Windows path examples

---

Validation summary

• Commands were designed to be copy-paste friendly for PowerShell.
• Existing macOS/Linux instructions remain available and unchanged in intent.
• Platform-specific differences are made explicit via tabs/callouts instead of implicit assumptions.

---

Reviewer checklist

• Windows tabs render correctly on all modified pages
• Existing macOS/Linux tabs still render and remain intact
• Playground Step 2 includes explicit clone step for all engines
• Presto path uses presto-tabularest-... (intentional upstream naming)
• Dev env page no longer depends on Unix-only shell flow for Windows users
• Troubleshooting section is actionable for Windows users

---

Notes for maintainers

This PR is intentionally documentation-only and platform-compatibility focused. No behavioral/runtime code changes are included.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Naman Jaiswal seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}