From b3f441d53fcf29e8189fe1cfd06ece00842ea73f Mon Sep 17 00:00:00 2001 From: Mohit Nagaraj Date: Sun, 12 Apr 2026 09:00:52 +0530 Subject: [PATCH 1/2] docs: fix quickstart guide with accurate prerequisites and setup info - Add conditional prerequisites table (Node.js 20+, Go 1.25+ per setup path) - Clarify what orchcli start -d runs in Docker vs host for each dev mode - Fix manual setup: add working config.yaml values, correct MONGO_URI for Docker-based MongoDB (no auth), add .env.local step for UI - Fix exec example: postgres -> mongodb - Expand Required Core Configuration table with optional fields - Fix Go install command to use correct module path (github.com/kubeorch/cli) Fixes #14 Signed-off-by: Mohit Nagaraj --- src/content/docs/guides/quickstart.md | 97 +++++++++++++++++++++------ 1 file changed, 76 insertions(+), 21 deletions(-) diff --git a/src/content/docs/guides/quickstart.md b/src/content/docs/guides/quickstart.md index a5bf057..5cb7f36 100644 --- a/src/content/docs/guides/quickstart.md +++ b/src/content/docs/guides/quickstart.md @@ -3,13 +3,23 @@ title: Quick Start description: Get KubeOrch running locally in minutes using orchcli. --- -The fastest way to get KubeOrch running is with **orchcli**, the official developer CLI. It handles Docker Compose orchestration, repository cloning, and dependency installation automatically. +The fastest way to get KubeOrch running is with **orchcli**, the official developer CLI. It handles Docker Compose orchestration, repository cloning, dependency installation, and configuration automatically. ## Prerequisites - **Docker** and **Docker Compose** (v2) installed and running - **Git** installed (orchcli can auto-install it on Linux/macOS) +Depending on your setup path, you may also need: + +| Setup | Additional Requirements | +|-------|----------------------| +| Production Mode | None -- everything runs in Docker | +| Frontend Development | **Node.js 20+** | +| Backend Development | None -- Go runs inside Docker via Air | +| Full Stack Development | **Node.js 20+** and **Go 1.25+** | +| Manual Setup | **Node.js 20+** and **Go 1.25+** | + ## Install orchcli ```bash @@ -39,10 +49,8 @@ Run the full platform from pre-built Docker images -- no source code needed. # Create a project directory mkdir kubeorch && cd kubeorch -# Initialize (production mode -- no repos cloned) +# Initialize and start orchcli init - -# Start all services in background orchcli start -d ``` @@ -75,17 +83,21 @@ orchcli stop -v # Stop and remove volumes (clean slate) ## Development Setup: Full Stack -For contributing to both frontend and backend. +For contributing to both frontend and backend. Requires **Node.js 20+** and **Go 1.25+**. ```bash mkdir kubeorch && cd kubeorch -# Clone both repos + install dependencies +# Clone both repos, install deps, and generate config files orchcli init --fork-ui --fork-core # Start MongoDB in Docker orchcli start -d +``` +Then in separate terminals: + +```bash # Terminal 1: Start Core backend (hot reload with Air) cd core && air @@ -93,18 +105,24 @@ cd core && air cd ui && npm run dev ``` +In this mode, `orchcli start -d` only runs **MongoDB** in Docker. Both Core and UI run on your host machine with hot reload. + +`orchcli init` automatically generates: +- `core/config.yaml` -- with random JWT secret, encryption key, and MongoDB URI pointing to `localhost:27017` +- `ui/.env.local` -- with `NEXT_PUBLIC_API_URL` pointing to the Core API + Edit files in `core/` or `ui/` -- changes hot-reload automatically. --- ## Development Setup: Frontend Only -For UI development without needing Go installed. +For UI development without needing Go installed. Requires **Node.js 20+**. ```bash mkdir kubeorch && cd kubeorch -# Clone UI repo only +# Clone UI repo, install deps, and generate .env.local orchcli init --fork-ui # Start MongoDB + Core API in Docker @@ -114,25 +132,29 @@ orchcli start -d cd ui && npm run dev ``` -The Core API runs from a Docker image at `localhost:3000`. You only need Node.js. +In this mode, `orchcli start -d` runs **MongoDB and Core API** in Docker. The Core API is available at `localhost:3000`. You only need Node.js. + +`orchcli init` automatically generates `ui/.env.local` with the API URL. --- ## Development Setup: Backend Only -For backend development without needing Node.js installed. +For backend development without needing Node.js installed. No Go installation required on the host either -- the Core code is volume-mounted into a Docker container running Air for hot reload. ```bash mkdir kubeorch && cd kubeorch -# Clone Core repo only +# Clone Core repo, install deps, and generate config.yaml orchcli init --fork-core # Start everything (Core with mounted code + hot reload via Air) orchcli start -d ``` -Your Core source code is volume-mounted into the Docker container. Edit files locally and they hot-reload inside Docker -- no Go installation required on the host. +In this mode, `orchcli start -d` runs **MongoDB, Core (via Air), and UI** all in Docker. Your Core source code is volume-mounted, so edits on the host hot-reload inside the container. + +`orchcli init` automatically generates `core/config.yaml` with default values. --- @@ -143,7 +165,7 @@ External contributors can clone from their own forks: ```bash mkdir kubeorch && cd kubeorch -# Clone from your fork +# Clone from your fork (config files are auto-generated) orchcli init --fork-ui=youruser/ui --fork-core=youruser/core # Upstream remote is auto-configured @@ -170,6 +192,7 @@ orchcli debug # Execute a command inside a container orchcli exec core sh orchcli exec ui sh +orchcli exec mongodb mongosh kubeorchestra # View recent logs for a specific service orchcli logs --tail 50 core @@ -179,7 +202,7 @@ orchcli logs --tail 50 core ## Manual Setup (Without orchcli) -If you prefer manual setup without the CLI: +If you prefer manual setup without the CLI. Requires **Node.js 20+** and **Go 1.25+**. ### 1. Start MongoDB @@ -195,7 +218,21 @@ docker run -d --name kubeorch-mongo \ ```bash git clone https://github.com/KubeOrch/core.git && cd core cp config.yaml.example config.yaml -# Edit config.yaml: set MONGO_URI, JWT_SECRET, ENCRYPTION_KEY +``` + +Edit `config.yaml` with these minimal values for local development: + +```yaml +MONGO_URI: "mongodb://localhost:27017/kubeorch" +JWT_SECRET: "any-secret-key-for-local-dev" +ENCRYPTION_KEY: "any-encryption-key-for-local-dev" +PORT: 3000 +GIN_MODE: debug +``` + +Then start the server: + +```bash go run main.go ``` @@ -204,14 +241,32 @@ go run main.go ```bash git clone https://github.com/KubeOrch/ui.git && cd ui npm install -# Create .env.local with: NEXT_PUBLIC_API_URL=http://localhost:3000/v1/api +``` + +Create a `.env.local` file: + +``` +NEXT_PUBLIC_API_URL=http://localhost:3000/v1/api +``` + +Then start the dev server: + +```bash npm run dev ``` +The UI will be available at `http://localhost:3001`. + ### Required Core Configuration -| Variable | Description | -|----------|-------------| -| `MONGO_URI` | MongoDB connection string (e.g., `mongodb://localhost:27017/kubeorch`) | -| `JWT_SECRET` | Secret key for JWT tokens | -| `ENCRYPTION_KEY` | Key for encrypting cluster credentials at rest | +These are the key settings. For the full reference including authentication providers (OIDC, OAuth2), CORS, and all available options, see the [Configuration Reference](/reference/configuration/). + +| Variable | Required | Description | +|----------|----------|-------------| +| `MONGO_URI` | Yes | MongoDB connection string (e.g., `mongodb://localhost:27017/kubeorch`) | +| `JWT_SECRET` | Yes | Secret key for signing JWT tokens | +| `ENCRYPTION_KEY` | No | Key for encrypting cluster credentials at rest | +| `PORT` | No | Server port (default: `3000`) | +| `GIN_MODE` | No | `debug` or `release` (default: `debug`) | +| `BASE_URL` | No | Backend URL for OAuth callbacks (default: `http://localhost:3000`) | +| `FRONTEND_URL` | No | Frontend URL for OAuth redirects (default: `http://localhost:3001`) | From 866131ed765bd6f530691196ad4de6147fc6d2ca Mon Sep 17 00:00:00 2001 From: Mohit Nagaraj Date: Mon, 20 Apr 2026 22:07:51 +0530 Subject: [PATCH 2/2] docs: fix quickstart with PR feedback and platform tabs - Fix database name: kubeorchestra -> kubeorch (bot feedback) - Fix ENCRYPTION_KEY requirement: No -> Yes (needed for clusters) - Convert to .mdx for component support - Add platform tabs for installation (macOS/Linux, Windows, NPM, Go) - Add winget and Scoop install methods for Windows Signed-off-by: Mohit Nagaraj --- .../guides/{quickstart.md => quickstart.mdx} | 43 +++++++++++++------ 1 file changed, 31 insertions(+), 12 deletions(-) rename src/content/docs/guides/{quickstart.md => quickstart.mdx} (89%) diff --git a/src/content/docs/guides/quickstart.md b/src/content/docs/guides/quickstart.mdx similarity index 89% rename from src/content/docs/guides/quickstart.md rename to src/content/docs/guides/quickstart.mdx index 5cb7f36..001e337 100644 --- a/src/content/docs/guides/quickstart.md +++ b/src/content/docs/guides/quickstart.mdx @@ -3,6 +3,8 @@ title: Quick Start description: Get KubeOrch running locally in minutes using orchcli. --- +import { Tabs, TabItem } from '@astrojs/starlight/components'; + The fastest way to get KubeOrch running is with **orchcli**, the official developer CLI. It handles Docker Compose orchestration, repository cloning, dependency installation, and configuration automatically. ## Prerequisites @@ -22,16 +24,33 @@ Depending on your setup path, you may also need: ## Install orchcli -```bash -# Option 1: Shell script (Linux/macOS) -curl -sfL https://raw.githubusercontent.com/KubeOrch/cli/main/install.sh | sh - -# Option 2: NPM (all platforms) -npm install -g @kubeorch/cli - -# Option 3: Go -go install github.com/kubeorch/cli@latest -``` + + + ```bash + curl -sfL https://raw.githubusercontent.com/KubeOrch/cli/main/install.sh | sh + ``` + + + ```bash + winget install kubeorch.cli + ``` + *Or use [Scoop](https://scoop.sh):* + ```bash + scoop bucket add kubeorch https://github.com/KubeOrch/scoop + scoop install orchcli + ``` + + + ```bash + npm install -g @kubeorch/cli + ``` + + + ```bash + go install github.com/kubeorch/cli@latest + ``` + + Verify installation: @@ -192,7 +211,7 @@ orchcli debug # Execute a command inside a container orchcli exec core sh orchcli exec ui sh -orchcli exec mongodb mongosh kubeorchestra +orchcli exec mongodb mongosh kubeorch # View recent logs for a specific service orchcli logs --tail 50 core @@ -265,7 +284,7 @@ These are the key settings. For the full reference including authentication prov |----------|----------|-------------| | `MONGO_URI` | Yes | MongoDB connection string (e.g., `mongodb://localhost:27017/kubeorch`) | | `JWT_SECRET` | Yes | Secret key for signing JWT tokens | -| `ENCRYPTION_KEY` | No | Key for encrypting cluster credentials at rest | +| `ENCRYPTION_KEY` | Yes | Key for encrypting cluster credentials at rest | | `PORT` | No | Server port (default: `3000`) | | `GIN_MODE` | No | `debug` or `release` (default: `debug`) | | `BASE_URL` | No | Backend URL for OAuth callbacks (default: `http://localhost:3000`) |