💡 Idea Check
@@ -192,6 +394,66 @@ export default function IdeaPage() { {loading ? "Analyzing..." : "Assess Idea"} + +
+
+
+ 
+ 
+ 
+ 
+ 
+
+
Open-source intelligence engine for discovering, evaluating, and adopting open-source libraries, frameworks, and agent skills.
@@ -99,7 +107,7 @@ docker compose up -d Important: Owlscope does not provide shared AI provider keys. You must supply your own API keys for LLM-powered features. -The Web App will be available at `http://localhost:3000` and the API at `http://localhost:8000`. +The Web App will be available at `http://127.0.0.1:3100` and the API at `http://127.0.0.1:8010`. ### Local Development @@ -121,7 +129,7 @@ DEEPSEEK_API_KEY=your_deepseek_key EOF # Start the API server -uvicorn src.api.main:app --reload --port 8000 +uvicorn src.api.main:app --reload --host 127.0.0.1 --port 8010 ``` #### Web App (Next.js) @@ -140,6 +148,24 @@ pip install -e ".[cli]" # Search for projects owlscope search "Python async HTTP client with HTTP/2" + +# Ops preflight (local-first) +owlscope ops preflight + +# Ops deploy (local direct mode, docker as fallback) +owlscope ops deploy --mode local + +# Include frontend startup and checks +owlscope ops deploy --mode local --with-web + +# Run checks without leaving background processes +owlscope ops deploy --mode local --with-web --no-detached + +# Ops deploy via docker explicitly +owlscope ops deploy --mode docker + +# Stop processes started by CLI deploy +owlscope ops stop ``` ## Usage Guidelines @@ -170,37 +196,103 @@ Notes: - The integration suite is excluded from default test runs. - CI always runs this test in a dedicated job with PostgreSQL + Redis services. +## Release Preflight + +Use these commands before deployment: + +```bash +# Validate production environment vars +python scripts/validate_env.py --mode prod + +# One-command release validation (tests + build + smoke) +bash scripts/release_check.sh + +# Include black-box integration test in the same run +OWLSCOPE_RELEASE_CHECK_INTEGRATION=1 bash scripts/release_check.sh +``` + +Production-readiness docs: +- Deployment runbook: `docs/deployment.md` +- Migration/rollback: `docs/migrations.md` +- Smoke checklist: `docs/smoke-test.md` +- Release checklist: `docs/release-checklist.md` + +Production launch commands: + +```bash +docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build +bash scripts/post_deploy_check.sh +``` + +CLI-first alternative: + +```bash +owlscope ops deploy --mode local +# if needed: owlscope ops deploy --mode docker +# include web checks: owlscope ops check --with-web +# stop local managed processes: owlscope ops stop +``` + ## API Reference ### REST API ```bash # Search -curl -X POST http://localhost:8000/api/v1/search \ +curl -X POST http://127.0.0.1:8010/api/v1/search \ -H "Content-Type: application/json" \ -d '{"query": "lightweight Python web framework"}' # Evaluate a project -curl http://localhost:8000/api/v1/evaluate/github:library:encode/httpx +curl http://127.0.0.1:8010/api/v1/evaluate/github:library:encode/httpx # Compare projects -curl -X POST http://localhost:8000/api/v1/compare \ +curl -X POST http://127.0.0.1:8010/api/v1/compare \ -H "Content-Type: application/json" \ -d '{"projects": ["github:library:fastapi/fastapi", "github:library:pallets/flask", "github:library:django/django"]}' # Assess whether an idea is already implemented -curl -X POST http://localhost:8000/api/v1/idea/assess \ +curl -X POST http://127.0.0.1:8010/api/v1/idea/assess \ + -H "Content-Type: application/json" \ + -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}' + +# Export assessment report as Markdown +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/export?format=markdown" \ -H "Content-Type: application/json" \ -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}' +# Export assessment report as JSON envelope +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/export?format=json" \ + -H "Content-Type: application/json" \ + -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}' + +# Batch assess multiple ideas +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch" \ + -H "Content-Type: application/json" \ + -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}' + +# Export batch assessment report as Markdown +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch/export?format=markdown" \ + -H "Content-Type: application/json" \ + -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}' + +# Export batch assessment report as JSON envelope +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch/export?format=json" \ + -H "Content-Type: application/json" \ + -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}' + # Response includes: # - verdict + existing_project_probability # - action_recommendation (build|fork|integrate) + action_rationale # - decision_signals for explainability # - similar_projects with evidence_snippets +# - export endpoint supports markdown/json report output +# - batch endpoint returns per-idea results + verdict counts +# - batch supports max_concurrency and per_item_timeout_seconds +# - batch export endpoint supports markdown/json report output ``` -Full API documentation available at `http://localhost:8000/docs` (Swagger UI) or `http://localhost:8000/redoc` (ReDoc). +Full API documentation available at `http://127.0.0.1:8010/docs` (Swagger UI) or `http://127.0.0.1:8010/redoc` (ReDoc). ### MCP Protocol diff --git a/README.zh-CN.md b/README.zh-CN.md index e53bb62..7e675bd 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -13,6 +13,14 @@ ``` +
+
开源情报引擎：帮助开发者与 AI Agent 检索、评估、推荐开源项目与 Agent Skills，并在立项阶段避免重复造轮子。
@@ -74,8 +82,8 @@ docker compose up -d ``` 启动后： -- Web: http://localhost:3000 -- API: http://localhost:8000 +- Web: http://127.0.0.1:3100 +- API: http://127.0.0.1:8010 重要说明：Owlscope 不提供共享 AI Key。所有 LLM 功能都需要用户自行配置 API Key。 @@ -96,7 +104,7 @@ DEEPSEEK_API_KEY=your_deepseek_key # ANTHROPIC_API_KEY=your_anthropic_key EOF -uvicorn src.api.main:app --reload --port 8000 +uvicorn src.api.main:app --reload --host 127.0.0.1 --port 8010 ``` 前端： @@ -106,6 +114,29 @@ npm install npm run dev ``` +CLI： +```bash +pip install -e ".[cli]" + +# 发布前预检 +owlscope ops preflight + +# 本地直跑优先（失败可自动回退 Docker） +owlscope ops deploy --mode local + +# 包含前端启动与校验 +owlscope ops deploy --mode local --with-web + +# 校验完成后自动回收本次启动进程 +owlscope ops deploy --mode local --with-web --no-detached + +# 显式走 Docker +owlscope ops deploy --mode docker + +# 停止 CLI 启动的本地进程 +owlscope ops stop +``` + ## 使用指南 - BYOK（自带 Key）：使用 LLM 功能前，必须在 `.env` 配置你自己的 API Key。 @@ -134,18 +165,80 @@ pytest -q -m integration tests/integration/test_compare_blackbox.py - 默认测试不会执行 integration 套件。 - CI 会在独立 Job 中（PostgreSQL + Redis）强制执行该测试。 +## 发布前预检 + +部署前建议执行： + +```bash +# 校验生产环境变量 +python scripts/validate_env.py --mode prod + +# 一键发布前校验（测试 + 构建 + 冒烟） +bash scripts/release_check.sh + +# 在同一流程中包含 integration 黑盒测试 +OWLSCOPE_RELEASE_CHECK_INTEGRATION=1 bash scripts/release_check.sh +``` + +上线文档： +- 部署 Runbook：`docs/deployment.md` +- 迁移/回滚：`docs/migrations.md` +- 冒烟检查：`docs/smoke-test.md` +- 发布清单：`docs/release-checklist.md` + +生产部署命令： + +```bash +docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build +bash scripts/post_deploy_check.sh +``` + +CLI 方式（优先本地直跑）： + +```bash +owlscope ops deploy --mode local +# 备选：owlscope ops deploy --mode docker +# 包含前端检查：owlscope ops check --with-web +# 停止 CLI 托管进程：owlscope ops stop +``` + ## API 参考 ```bash # 语义搜索 -curl -X POST http://localhost:8000/api/v1/search \ +curl -X POST http://127.0.0.1:8010/api/v1/search \ -H "Content-Type: application/json" \ -d '{"query": "lightweight Python web framework"}' # 想法评估（是否已有开源实现） -curl -X POST http://localhost:8000/api/v1/idea/assess \ +curl -X POST http://127.0.0.1:8010/api/v1/idea/assess \ + -H "Content-Type: application/json" \ + -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}' + +# 导出 Markdown 报告 +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/export?format=markdown" \ -H "Content-Type: application/json" \ -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}' + +# 导出 JSON 报告 +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/export?format=json" \ + -H "Content-Type: application/json" \ + -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}' + +# 批量评估多个想法 +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch" \ + -H "Content-Type: application/json" \ + -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}' + +# 导出批量评估 Markdown 报告 +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch/export?format=markdown" \ + -H "Content-Type: application/json" \ + -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}' + +# 导出批量评估 JSON 报告 +curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch/export?format=json" \ + -H "Content-Type: application/json" \ + -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}' ``` 响应包含： @@ -153,6 +246,10 @@ curl -X POST http://localhost:8000/api/v1/idea/assess \ - action_recommendation（build/fork/integrate） - decision_signals（判定依据） - similar_projects 与 evidence_snippets +- 导出接口支持 markdown/json 两种报告格式 +- 批量接口返回逐条结果和 verdict 统计 +- 批量接口支持 max_concurrency 与 per_item_timeout_seconds +- 批量导出接口支持 markdown/json 两种报告格式 ## 自托管 diff --git a/cli/__init__.py b/cli/__init__.py index b25b240..31a027c 100644 --- a/cli/__init__.py +++ b/cli/__init__.py @@ -2,9 +2,15 @@ from __future__ import annotations +import json import os +import signal +import subprocess import sys +import time from pathlib import Path +from urllib.error import URLError +from urllib.request import urlopen import typer from rich.console import Console @@ -22,16 +28,333 @@ help="🦉 Owlscope CLI — search, evaluate, and compare open-source projects and Agent Skills.", no_args_is_help=True, ) +ops_app = typer.Typer(help="Release and deployment operations (local-first, docker optional).") +app.add_typer(ops_app, name="ops") console = Console() +ROOT_DIR = Path(__file__).resolve().parent.parent +STATE_FILE = Path("/tmp/owlscope-cli-runtime.json") def _get_client() -> OwlscopeClient: return OwlscopeClient(OwlscopeConfig( - base_url=os.environ.get("OWLSCOPE_API_URL", "http://localhost:8000"), + base_url=os.environ.get("OWLSCOPE_API_URL", "http://127.0.0.1:8010"), api_key=os.environ.get("OWLSCOPE_API_KEY"), )) +def _run(cmd: list[str], env: dict[str, str] | None = None, cwd: Path | None = None) -> None: + subprocess.run(cmd, cwd=str(cwd or ROOT_DIR), env=env, check=True) + + +def _load_state() -> dict[str, object]: + if not STATE_FILE.exists(): + return {} + try: + return json.loads(STATE_FILE.read_text(encoding="utf-8")) + except Exception: + return {} + + +def _save_state(state: dict[str, object]) -> None: + STATE_FILE.write_text(json.dumps(state, indent=2), encoding="utf-8") + + +def _clear_state() -> None: + try: + STATE_FILE.unlink() + except FileNotFoundError: + pass + + +def _is_pid_running(pid: int) -> bool: + try: + os.kill(pid, 0) + return True + except OSError: + return False + + +def _stop_pid(pid: int, name: str, timeout_s: float = 8.0) -> bool: + if not _is_pid_running(pid): + return False + + try: + os.kill(pid, signal.SIGTERM) + except OSError: + return False + + deadline = time.time() + timeout_s + while time.time() < deadline: + if not _is_pid_running(pid): + return True + time.sleep(0.2) + + try: + os.kill(pid, signal.SIGKILL) + return True + except OSError: + console.print(f"[yellow]Unable to force-stop {name} process (pid={pid})[/yellow]") + return False + + +def _is_healthy(api_base: str) -> bool: + try: + with urlopen(f"{api_base}/health", timeout=2.0) as resp: + return resp.status == 200 + except (URLError, TimeoutError, ValueError): + return False + + +def _wait_health(api_base: str, timeout_s: int = 90) -> bool: + deadline = time.time() + timeout_s + while time.time() < deadline: + if _is_healthy(api_base): + return True + time.sleep(1) + return False + + +def _is_url_ok(url: str) -> bool: + try: + with urlopen(url, timeout=2.0) as resp: + return 200 <= resp.status < 500 + except (URLError, TimeoutError, ValueError): + return False + + +def _wait_url(url: str, timeout_s: int = 120) -> bool: + deadline = time.time() + timeout_s + while time.time() < deadline: + if _is_url_ok(url): + return True + time.sleep(1) + return False + + +def _deploy_docker(api_base: str, web_base: str, with_web: bool) -> None: + console.print("[bold cyan]Deploying with Docker (backup path)...[/bold cyan]") + _run([ + "docker", + "compose", + "-f", + "docker-compose.yml", + "-f", + "docker-compose.prod.yml", + "up", + "-d", + "--build", + ]) + env = os.environ.copy() + env["OWLSCOPE_API_BASE"] = api_base + _run(["bash", "scripts/post_deploy_check.sh"], env=env) + if with_web: + env["OWLSCOPE_WEB_BASE"] = web_base + _run(["bash", "scripts/check_web.sh"], env=env) + + +@ops_app.command("preflight") +def ops_preflight( + integration: bool = typer.Option(False, "--integration", help="Include integration compare test"), +) -> None: + """Run one-command release preflight checks.""" + env = os.environ.copy() + env["OWLSCOPE_RELEASE_CHECK_INTEGRATION"] = "1" if integration else "0" + _run(["bash", "scripts/release_check.sh"], env=env) + console.print("[green]Preflight checks passed.[/green]") + + +@ops_app.command("check") +def ops_check( + api_base: str = typer.Option("http://127.0.0.1:8010", help="API base URL"), + with_web: bool = typer.Option(False, "--with-web", help="Also validate web endpoint"), + web_base: str = typer.Option("http://127.0.0.1:3100", help="Web base URL"), +) -> None: + """Run post-deploy checks against a running API.""" + env = os.environ.copy() + env["OWLSCOPE_API_BASE"] = api_base + _run(["bash", "scripts/post_deploy_check.sh"], env=env) + if with_web: + env["OWLSCOPE_WEB_BASE"] = web_base + _run(["bash", "scripts/check_web.sh"], env=env) + console.print("[green]Post-deploy checks passed.[/green]") + + +@ops_app.command("deploy") +def ops_deploy( + mode: str = typer.Option("local", help="Deployment mode: local or docker"), + api_host: str = typer.Option("127.0.0.1", help="API host for local mode"), + api_port: int = typer.Option(8010, help="API port for local mode"), + with_web: bool = typer.Option(False, "--with-web", help="Also ensure web is started and validated"), + web_host: str = typer.Option("127.0.0.1", help="Web host for local mode"), + web_port: int = typer.Option(3100, help="Web port for local mode"), + web_mode: str = typer.Option("start", help="Web mode for local: start or dev"), + detached: bool = typer.Option(True, "--detached/--no-detached", help="Keep CLI-started processes running after checks"), + fallback_docker: bool = typer.Option(True, "--fallback-docker/--no-fallback-docker", help="Use docker deployment if local mode fails"), +) -> None: + """Deploy with local-first strategy; optionally fallback to docker.""" + selected_mode = mode.strip().lower() + api_base = f"http://{api_host}:{api_port}" + web_base = f"http://{web_host}:{web_port}" + selected_web_mode = web_mode.strip().lower() + + if selected_mode not in {"local", "docker"}: + console.print("[red]mode must be 'local' or 'docker'[/red]") + raise typer.Exit(1) + + if selected_web_mode not in {"start", "dev"}: + console.print("[red]web-mode must be 'start' or 'dev'[/red]") + raise typer.Exit(1) + + if selected_mode == "docker": + _deploy_docker(api_base, web_base, with_web) + console.print("[green]Docker deploy completed.[/green]") + return + + env = os.environ.copy() + started_state: dict[str, object] = {} + api_proc: subprocess.Popen[str] | None = None + web_proc: subprocess.Popen[str] | None = None + try: + _run([sys.executable, "scripts/validate_env.py", "--mode", "prod"], env=env) + + log_file = "/tmp/owlscope-cli-local-api.log" + web_log_file = "/tmp/owlscope-cli-local-web.log" + + if not _is_healthy(api_base): + console.print("[bold cyan]Starting local API (direct mode)...[/bold cyan]") + log_handle = open(log_file, "a", encoding="utf-8") + api_proc = subprocess.Popen( + [ + sys.executable, + "-m", + "uvicorn", + "src.api.main:app", + "--host", + api_host, + "--port", + str(api_port), + "--log-level", + "warning", + ], + cwd=str(ROOT_DIR), + stdout=log_handle, + stderr=subprocess.STDOUT, + text=True, + ) + + if not _wait_health(api_base): + raise RuntimeError("Local API did not become healthy in time") + + started_state["api"] = { + "pid": api_proc.pid, + "host": api_host, + "port": api_port, + "base": api_base, + "log": log_file, + } + + env["OWLSCOPE_API_BASE"] = api_base + _run(["bash", "scripts/post_deploy_check.sh"], env=env) + + if with_web: + if not _is_url_ok(web_base): + console.print("[bold cyan]Starting local Web...[/bold cyan]") + web_env = os.environ.copy() + web_env["OWLSCOPE_API_ORIGIN"] = api_base + web_log_handle = open(web_log_file, "a", encoding="utf-8") + if selected_web_mode == "start": + _run(["npm", "run", "build"], env=web_env, cwd=ROOT_DIR / "web") + web_proc = subprocess.Popen( + ["npx", "next", "start", "-H", web_host, "-p", str(web_port)], + cwd=str(ROOT_DIR / "web"), + env=web_env, + stdout=web_log_handle, + stderr=subprocess.STDOUT, + text=True, + ) + else: + web_proc = subprocess.Popen( + ["npx", "next", "dev", "-H", web_host, "-p", str(web_port)], + cwd=str(ROOT_DIR / "web"), + env=web_env, + stdout=web_log_handle, + stderr=subprocess.STDOUT, + text=True, + ) + + if not _wait_url(web_base): + raise RuntimeError("Local web did not become ready in time") + + started_state["web"] = { + "pid": web_proc.pid, + "host": web_host, + "port": web_port, + "base": web_base, + "mode": selected_web_mode, + "log": web_log_file, + } + + env["OWLSCOPE_WEB_BASE"] = web_base + _run(["bash", "scripts/check_web.sh"], env=env) + + console.print("[green]Local deployment checks passed.[/green]") + if started_state and detached: + _save_state(started_state) + console.print(f"[dim]Runtime state saved: {STATE_FILE}[/dim]") + if "api" in started_state: + console.print(f"[dim]Local API started by CLI, PID={started_state['api']['pid']}, logs={started_state['api']['log']}[/dim]") + if "web" in started_state: + console.print(f"[dim]Local Web started by CLI, PID={started_state['web']['pid']}, logs={started_state['web']['log']}[/dim]") + console.print("[dim]Use 'owlscope ops stop' to stop CLI-managed processes.[/dim]") + elif started_state and not detached: + if "web" in started_state: + _stop_pid(int(started_state["web"]["pid"]), "web") + if "api" in started_state: + _stop_pid(int(started_state["api"]["pid"]), "api") + _clear_state() + console.print("[dim]Stopped CLI-started processes because --no-detached was set.[/dim]") + except Exception as exc: + if started_state.get("web"): + _stop_pid(int(started_state["web"]["pid"]), "web") + if started_state.get("api"): + _stop_pid(int(started_state["api"]["pid"]), "api") + _clear_state() + console.print(f"[yellow]Local mode failed: {exc}[/yellow]") + if not fallback_docker: + raise typer.Exit(1) + _deploy_docker(api_base, web_base, with_web) + console.print("[green]Fallback docker deploy completed.[/green]") + + +@ops_app.command("stop") +def ops_stop() -> None: + """Stop API/Web processes that were started by `owlscope ops deploy`.""" + state = _load_state() + if not state: + console.print("[yellow]No CLI-managed runtime state found.[/yellow]") + return + + stopped_any = False + + web = state.get("web") + if isinstance(web, dict) and "pid" in web: + pid = int(web["pid"]) + if _stop_pid(pid, "web"): + console.print(f"[green]Stopped web process (pid={pid}).[/green]") + stopped_any = True + + api = state.get("api") + if isinstance(api, dict) and "pid" in api: + pid = int(api["pid"]) + if _stop_pid(pid, "api"): + console.print(f"[green]Stopped api process (pid={pid}).[/green]") + stopped_any = True + + _clear_state() + if not stopped_any: + console.print("[yellow]State found, but managed processes were already stopped.[/yellow]") + + @app.command() def search( query: str = typer.Argument(..., help="Natural language search query"), diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml new file mode 100644 index 0000000..0e104e6 --- /dev/null +++ b/docker-compose.prod.yml @@ -0,0 +1,24 @@ +services: + api: + restart: unless-stopped + command: uvicorn src.api.main:app --host 0.0.0.0 --port 8000 + volumes: [] + environment: + - DEBUG=false + + web: + restart: unless-stopped + volumes: [] + environment: + - NODE_ENV=production + - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL:-http://127.0.0.1:8010} + - OWLSCOPE_API_ORIGIN=${OWLSCOPE_API_ORIGIN:-http://api:8000} + + postgres: + restart: unless-stopped + + redis: + restart: unless-stopped + + qdrant: + restart: unless-stopped diff --git a/docker-compose.yml b/docker-compose.yml index 5566116..bdc35fe 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -5,7 +5,7 @@ services: context: . dockerfile: docker/Dockerfile.api ports: - - "8000:8000" + - "8010:8000" env_file: - .env depends_on: @@ -26,11 +26,12 @@ services: context: ./web dockerfile: ../docker/Dockerfile.web ports: - - "3000:3000" + - "3100:3000" depends_on: - api environment: - - NEXT_PUBLIC_API_URL=http://api:8000 + - NEXT_PUBLIC_API_URL=http://127.0.0.1:8010 + - OWLSCOPE_API_ORIGIN=http://api:8000 volumes: - ./web/src:/app/src diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..b88061d --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,56 @@ +# Deployment Runbook + +This runbook covers a safe baseline deployment for Owlscope. + +## 1. Preflight + +- Validate env vars: + - `python scripts/validate_env.py --mode prod` +- Run release checks: + - `bash scripts/release_check.sh` +- Run integration compare test: + - `bash scripts/run_integration_compare.sh` + +## 2. Build and Launch + +- Build web: + - `cd web && npm ci && npm run build` +- CLI-first launch (local direct mode): + - `owlscope ops deploy --mode local` +- CLI launch with frontend validation: + - `owlscope ops deploy --mode local --with-web` +- Ephemeral run (auto-stop after checks): + - `owlscope ops deploy --mode local --with-web --no-detached` +- Start services (production profile with override): + - `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build` +- CLI docker backup path: + - `owlscope ops deploy --mode docker` + - `owlscope ops deploy --mode docker --with-web` + +## 3. Post-Deploy Verification + +- Health: + - `curl http://127.0.0.1:8010/health` +- Admin monitor: + - `curl http://127.0.0.1:8010/api/v1/admin/monitor` +- One-command post-deploy checks: + - `bash scripts/post_deploy_check.sh` + - `owlscope ops check` + - `owlscope ops check --with-web` +- Stop CLI-managed local processes: + - `owlscope ops stop` +- Rate-limit headers: + - `bash scripts/check_rate_limit.sh` +- Core smoke APIs: + - `/api/v1/search` + - `/api/v1/evaluate/{id}` + - `/api/v1/compare` + - `/api/v1/idea/assess` + +## 4. Rollback + +- Roll app image/version back to the previous known-good release. +- Run DB rollback only when schema migration requires it. +- Re-run smoke checks after rollback. + +See also: `docs/migrations.md` and `docs/smoke-test.md`. diff --git a/docs/migrations.md b/docs/migrations.md new file mode 100644 index 0000000..06a27b6 --- /dev/null +++ b/docs/migrations.md @@ -0,0 +1,34 @@ +# Database Migration and Rollback Guide + +Use Alembic for schema changes in production. + +## Forward Migration + +```bash +alembic upgrade head +``` + +## Rollback One Version + +```bash +alembic downgrade -1 +``` + +## Rollback to Specific Revision + +```bash +alembic downgrade