From 9e2fdb964306a5b8f506493e5e638535d529befa Mon Sep 17 00:00:00 2001
From: root <root@srv1491630.hstgr.cloud>
Date: Sat, 14 Mar 2026 05:01:09 +0000
Subject: [PATCH] Add prototype deployment workflow

---
 README.md                      | 11 ++++++
 docs/PROTOTYPE_DEPLOYMENT.md   | 64 ++++++++++++++++++++++++++++++++++
 scripts/check-prototype-env.sh | 52 +++++++++++++++++++++++++++
 scripts/prototype-up.sh        | 25 +++++++++++++
 4 files changed, 152 insertions(+)
 create mode 100644 docs/PROTOTYPE_DEPLOYMENT.md
 create mode 100755 scripts/check-prototype-env.sh
 create mode 100755 scripts/prototype-up.sh

diff --git a/README.md b/README.md
index 293535f2..955e1154 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,17 @@ pnpm typecheck
 pnpm --filter @lysnrai/platform-service dev
 ```
 
+## Prototype Deployment
+
+For a single-host prototype, use Docker Compose with the repo root [`docker-compose.yml`](/root/bytelyst.ai/repos/learning_ai_common_plat/docker-compose.yml).
+
+```bash
+cp .env.example .env
+./scripts/prototype-up.sh
+```
+
+See [docs/PROTOTYPE_DEPLOYMENT.md](docs/PROTOTYPE_DEPLOYMENT.md) for the required environment variables and day-to-day commands.
+
 ## Current Capability Surface
 
 - **Shared packages** — 36 `@bytelyst/*` packages covering auth, config, API clients, storage, sync, telemetry, diagnostics, design tokens, SDK support, and testing.
diff --git a/docs/PROTOTYPE_DEPLOYMENT.md b/docs/PROTOTYPE_DEPLOYMENT.md
new file mode 100644
index 00000000..da390de7
--- /dev/null
+++ b/docs/PROTOTYPE_DEPLOYMENT.md
@@ -0,0 +1,64 @@
+# Prototype Deployment
+
+This repo is currently set up to run as a single-host prototype with Docker Compose.
+
+## What This Includes
+
+- `platform-service`
+- `extraction-service`
+- `mcp-server`
+- `gateway` (Traefik)
+- `loki`
+- `grafana`
+
+## What Stays External
+
+- Azure Cosmos DB
+- Azure Key Vault if you choose to use it
+- Any real API credentials such as Stripe or Gemini
+
+For the prototype phase, keep secrets in `.env` and keep state in managed external services rather than adding more local containers.
+
+## First-Time Setup
+
+```bash
+cp .env.example .env
+```
+
+Fill in at least:
+
+- `COSMOS_ENDPOINT`
+- `COSMOS_KEY`
+- `JWT_SECRET`
+
+If you want extraction features that call Gemini, also set:
+
+- `GEMINI_API_KEY`
+
+## Start The Stack
+
+```bash
+./scripts/prototype-up.sh
+```
+
+That script will:
+
+1. Validate the required environment variables.
+2. Build the shared packages needed by the Docker images.
+3. Build and start the Compose stack.
+
+## Day-To-Day Commands
+
+```bash
+docker compose ps
+docker compose logs -f platform-service
+docker compose logs -f extraction-service
+docker compose logs -f mcp-server
+docker compose down
+```
+
+## Notes
+
+- This is intended for early prototype use on a single machine.
+- Do not commit `.env`.
+- When the project moves to a more secure environment later, keep the same service boundaries and move secrets out of `.env` into a proper secret manager.
diff --git a/scripts/check-prototype-env.sh b/scripts/check-prototype-env.sh
new file mode 100755
index 00000000..aa95f96c
--- /dev/null
+++ b/scripts/check-prototype-env.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ENV_FILE="${1:-$REPO_ROOT/.env}"
+
+if [[ ! -f "$ENV_FILE" ]]; then
+  echo "Missing env file: $ENV_FILE"
+  echo "Copy .env.example to .env and fill in the required values."
+  exit 1
+fi
+
+required_vars=(
+  COSMOS_ENDPOINT
+  COSMOS_KEY
+  JWT_SECRET
+)
+
+optional_vars=(
+  GEMINI_API_KEY
+)
+
+missing_required=()
+missing_optional=()
+
+for var_name in "${required_vars[@]}"; do
+  value="$(grep -E "^${var_name}=" "$ENV_FILE" | tail -n 1 | cut -d= -f2- || true)"
+  if [[ -z "${value// }" ]] || [[ "$value" == your-* ]]; then
+    missing_required+=("$var_name")
+  fi
+done
+
+for var_name in "${optional_vars[@]}"; do
+  value="$(grep -E "^${var_name}=" "$ENV_FILE" | tail -n 1 | cut -d= -f2- || true)"
+  if [[ -z "${value// }" ]] || [[ "$value" == your-* ]]; then
+    missing_optional+=("$var_name")
+  fi
+done
+
+if ((${#missing_required[@]} > 0)); then
+  echo "Missing required environment variables in $ENV_FILE:"
+  printf '  - %s\n' "${missing_required[@]}"
+  exit 1
+fi
+
+echo "Required environment variables look present in $ENV_FILE."
+
+if ((${#missing_optional[@]} > 0)); then
+  echo "Optional variables not set:"
+  printf '  - %s\n' "${missing_optional[@]}"
+  echo "Extraction features that call Gemini may not work until these are configured."
+fi
diff --git a/scripts/prototype-up.sh b/scripts/prototype-up.sh
new file mode 100755
index 00000000..02462904
--- /dev/null
+++ b/scripts/prototype-up.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+if [[ ! -f .env ]]; then
+  echo "Missing .env in $REPO_ROOT"
+  echo "Run: cp .env.example .env"
+  exit 1
+fi
+
+"$REPO_ROOT/scripts/check-prototype-env.sh" "$REPO_ROOT/.env"
+"$REPO_ROOT/scripts/docker-prep.sh"
+
+echo "Starting prototype stack with Docker Compose..."
+docker compose up -d --build
+
+echo ""
+echo "Prototype stack started."
+echo "Useful commands:"
+echo "  docker compose ps"
+echo "  docker compose logs -f platform-service"
+echo "  docker compose logs -f extraction-service"
+echo "  docker compose logs -f mcp-server"