Add setup guide
This commit is contained in:
+117
@@ -0,0 +1,117 @@
|
||||
# Setup Guide (for future Replit Agents)
|
||||
|
||||
A short, copy-paste-friendly checklist to get this project running from a clean clone. Read this **before** restarting workflows or asking the user for credentials.
|
||||
|
||||
## What this project is
|
||||
|
||||
A pnpm monorepo with three artifacts:
|
||||
|
||||
| Artifact | Path | Port | Purpose |
|
||||
| --- | --- | --- | --- |
|
||||
| `api-server` | `artifacts/api-server` | `8080` | Express server. `/api/*` (health) + `/v1/*` OpenAI-compatible reverse proxy in front of OpenAI and Anthropic. |
|
||||
| `api-portal` | `artifacts/api-portal` | `24927` | React + Vite frontend that shows connection info and CherryStudio setup. |
|
||||
| `mockup-sandbox` | `artifacts/mockup-sandbox` | `8081` | Vite dev server for component previews. |
|
||||
|
||||
The proxy exposes `GET /v1/models` and `POST /v1/chat/completions`. Model variants are auto-generated by suffixing the base id with a reasoning effort, e.g. `gpt-5.2-low`, `claude-opus-4-6-high`. For Anthropic models the suffix maps to `thinking.budget_tokens`.
|
||||
|
||||
## Workflows (already configured in `.replit-artifact/artifact.toml` per artifact)
|
||||
|
||||
- `artifacts/api-portal: web` → `pnpm --filter @workspace/api-portal run dev`
|
||||
- `artifacts/api-server: API Server` → `pnpm --filter @workspace/api-server run dev`
|
||||
- `artifacts/mockup-sandbox: Component Preview Server` → `pnpm --filter @workspace/mockup-sandbox run dev`
|
||||
|
||||
Do **not** edit `artifact.toml` directly — use the artifacts skill helpers (`createArtifact`, `verifyAndReplaceArtifactToml`).
|
||||
|
||||
## Required env vars / secrets
|
||||
|
||||
The api-server instantiates the OpenAI and Anthropic SDKs at import time. If any of these are missing it crashes immediately on startup with `OpenAIError: Missing credentials` or similar.
|
||||
|
||||
| Name | How to set | Notes |
|
||||
| --- | --- | --- |
|
||||
| `AI_INTEGRATIONS_OPENAI_BASE_URL` | `setupReplitAIIntegrations({ providerSlug: "openai", ... })` | auto-set |
|
||||
| `AI_INTEGRATIONS_OPENAI_API_KEY` | same call | auto-set (dummy string for SDK; works alongside BASE_URL) |
|
||||
| `AI_INTEGRATIONS_ANTHROPIC_BASE_URL` | `setupReplitAIIntegrations({ providerSlug: "anthropic", ... })` | auto-set |
|
||||
| `AI_INTEGRATIONS_ANTHROPIC_API_KEY` | same call | auto-set |
|
||||
| `PROXY_API_KEY` | `requestEnvVar({ requestType: "secret", keys: ["PROXY_API_KEY"] })` | user-defined; bearer token clients send |
|
||||
|
||||
## One-shot setup script (in the JS sandbox)
|
||||
|
||||
```javascript
|
||||
// 1. Provision OpenAI + Anthropic via Replit AI Integrations
|
||||
await setupReplitAIIntegrations({
|
||||
providerSlug: "openai",
|
||||
providerUrlEnvVarName: "AI_INTEGRATIONS_OPENAI_BASE_URL",
|
||||
providerApiKeyEnvVarName: "AI_INTEGRATIONS_OPENAI_API_KEY",
|
||||
});
|
||||
await setupReplitAIIntegrations({
|
||||
providerSlug: "anthropic",
|
||||
providerUrlEnvVarName: "AI_INTEGRATIONS_ANTHROPIC_BASE_URL",
|
||||
providerApiKeyEnvVarName: "AI_INTEGRATIONS_ANTHROPIC_API_KEY",
|
||||
});
|
||||
|
||||
// 2. Ask the user for their proxy bearer token (suggest a random one)
|
||||
const crypto = await import("node:crypto");
|
||||
const suggested = crypto.randomBytes(24).toString("base64url");
|
||||
await requestEnvVar({
|
||||
requestType: "secret",
|
||||
keys: ["PROXY_API_KEY"],
|
||||
userMessage: `Bearer token for /v1/* on the proxy. Suggested: ${suggested}`,
|
||||
});
|
||||
```
|
||||
|
||||
Then in the shell:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
And restart all three workflows (in any order).
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# health
|
||||
curl -s http://localhost:8080/api/healthz
|
||||
# → {"status":"ok"}
|
||||
|
||||
# auth gate
|
||||
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/v1/models
|
||||
# → 401
|
||||
|
||||
# model list (replace with your secret)
|
||||
curl -s -H "Authorization: Bearer $PROXY_API_KEY" http://localhost:8080/v1/models | head -c 200
|
||||
|
||||
# portal
|
||||
curl -s http://localhost:24927/ | head -c 80
|
||||
# → <!DOCTYPE html> ...
|
||||
```
|
||||
|
||||
## Common gotchas
|
||||
|
||||
- **Port 8080 already in use after a crash loop.** Stale `node ./dist/index.mjs` processes from a previous failed start can hold the port. `ps -ef | grep dist/index.mjs` then `kill -9 <pid>` before restarting the workflow.
|
||||
- **mockup-sandbox transient `Cannot find package 'vite'` on first start.** It's a vite restart race after `pnpm install` invalidates `.vite-temp/`. A second restart of the workflow clears it.
|
||||
- **Do not edit `lib/integrations-*-server/src/client.ts`** if those packages are added later — the env-var wiring is auto-managed.
|
||||
- **`PROXY_API_KEY` is a bearer token, not an OAuth secret.** It only gates `/v1/*`; pick anything. Clients send `Authorization: Bearer <PROXY_API_KEY>`.
|
||||
- **Adding routes to the proxy:** the file is `artifacts/api-server/src/routes/proxy.ts`, mounted at `/v1` in `artifacts/api-server/src/app.ts`. Health/utility routes live under `artifacts/api-server/src/routes/` and are mounted at `/api`.
|
||||
|
||||
## File map (key paths)
|
||||
|
||||
```
|
||||
artifacts/
|
||||
api-server/
|
||||
src/app.ts # express setup, mounts /api and /v1
|
||||
src/routes/proxy.ts # /v1/models + /v1/chat/completions, OpenAI+Anthropic
|
||||
src/routes/health.ts # /api/healthz
|
||||
build.mjs # esbuild bundler
|
||||
api-portal/
|
||||
src/App.tsx # connection info + CherryStudio instructions
|
||||
vite.config.ts
|
||||
mockup-sandbox/
|
||||
vite.config.ts
|
||||
lib/
|
||||
api-spec/openapi.yaml # OpenAPI source for codegen
|
||||
api-zod/ # generated zod schemas
|
||||
api-client-react/ # generated react-query hooks
|
||||
db/ # drizzle schema (unused by the proxy itself)
|
||||
replit.md # high-level project overview
|
||||
```
|
||||
Reference in New Issue
Block a user