1 line
8.3 KiB
JSON
1 line
8.3 KiB
JSON
{"repo": "aevella/polaris-local-first", "files": {"DEPLOYMENT.md": {"1aac86c8e00260962d5d30362571c9f6bf7c0630": {"t": 1785595193.1706731, "n": 8015, "h": "fd5d385d27773f20", "c": "# Deployment\n\nPolaris has separate deployment paths for the source checkout, a web build,\nbackend API routes, and native wrappers. A working source build is not the same\nthing as an Android APK, iOS/TestFlight build, or hosted service release.\n\n## Quick Start\n\nRun the web app locally:\n\n```bash\nnpm i\nnpm run dev\n```\n\nBuild the static frontend:\n\n```bash\nnpm run build\n```\n\nThe production frontend is written to `dist/`.\n\n## Requirements\n\n- Node.js 20 or newer\n- npm\n- Android Studio or Android command line tools for Android builds\n- Xcode on macOS for iOS builds\n- Wrangler only if deploying `workers/polaris-api/`\n\n## Configuration\n\nCreate a local environment file when the frontend needs to talk to a backend on\nanother origin:\n\n```bash\ncp .env.example .env.local\n```\n\nSet:\n\n```bash\nVITE_POLARIS_API_ORIGIN=https://your-backend.example.com\n```\n\nLeave `VITE_POLARIS_API_ORIGIN` empty for same-origin web deployments where the\nfrontend and `/api` routes are served by the same host.\n\nProvider API keys are server-side secrets. `VITE_` variables are bundled into\nbrowser code, so provider keys fit serverless functions, Workers, native secure\nstorage, or another deployer-owned backend.\n\n## Local Web Development\n\n```bash\nnpm i\nnpm run dev\n```\n\nThe Vite dev server serves the shared frontend. It does not start backend API\nhandlers by itself.\n\nIf `VITE_POLARIS_API_ORIGIN` is set, Vite proxies `/api` to that origin. If it is\nnot set, `/api` stays relative to the current origin and will return 404 unless\nthe current host also serves API routes.\n\n## Static Web Deployment\n\nBuild the frontend:\n\n```bash\nnpm run build\n```\n\nDeploy `dist/` to any static host.\n\nFor chat routes, provider relay, image generation, embeddings, search,\ndiagnostics, or built-in model gateways, pair the static frontend with a backend\norigin and set `VITE_POLARIS_API_ORIGIN` at build time:\n\n```bash\nVITE_POLARIS_API_ORIGIN=https://api.example.com npm run build\n```\n\nThe static frontend keeps user data in the browser runtime. Deploying a new\nfrontend build does not automatically migrate a user's existing browser,\nAndroid, or iOS data.\n\nStatic hosting by itself does not create accounts, cloud sync, or a central\ndatabase. It only serves the app shell. User data remains in the user's current\nbrowser or native app storage unless the user explicitly exports, imports, or\nconnects a separate backend feature.\n\n## Same-Origin API Deployment\n\nThe `api/` directory contains Vercel-style serverless handlers. A same-origin\ndeployment serves both:\n\n- `dist/` for the frontend\n- `/api/...` for serverless routes\n\nTypical settings:\n\n```text\nInstall command: npm ci\nBuild command: npm run build\nOutput directory: dist\n```\n\nAdd server-side environment variables for the routes you enable. Common keys are\nlisted in [docs/connect-your-own-backend.md](docs/connect-your-own-backend.md).\n\nSome frontend paths refer to API capabilities that need additional handler work\nbefore they are complete in a managed public service. The route table in\n[docs/connect-your-own-backend.md](docs/connect-your-own-backend.md) marks those\nsurfaces.\n\n## Split Frontend And Backend\n\nUse a split deployment when the frontend is on one origin and the API is on\nanother:\n\n```bash\nVITE_POLARIS_API_ORIGIN=https://api.example.com npm run build\n```\n\nThe backend needs to allow the deployed frontend origin in CORS. For routes that\nforward provider credentials, receive diagnostics, or handle user content, keep\nCORS scoped to known frontend origins rather than wildcard origins.\n\nBackend origin and relay rules are documented in\n[docs/connect-your-own-backend.md](docs/connect-your-own-backend.md).\n\n## Backend Visibility\n\nA backend can see the traffic it handles. If it forwards provider requests,\nsearch requests, diagnostics, image generation, embeddings, or other model\ninputs, the backend operator may be able to inspect that content.\n\nA private Polaris install is safest with a backend the deployer operates or\nalready trusts. A reachable public backend is still a backend operated by\nsomeone else.\n\nConnecting a backend does not automatically enable account sync, shared cloud\nstorage, or remote backups. Those are separate product features and need their\nown data model, authentication, authorization, storage, migration, and deletion\nrules.\n\n## Cloudflare Worker Example\n\n`workers/polaris-api/` is a smaller Worker package for a built-in chat gateway.\nIt is not a full replacement for every `/api/...` route.\n\n```bash\ncd workers/polaris-api\nnpm ci\nnpm run typecheck\n```\n\nCreate the KV namespace used for rate limits, put the namespace id in\n`workers/polaris-api/wrangler.toml`, and set provider secrets:\n\n```bash\nnpx wrangler kv namespace create RATE_LIMIT\nnpx wrangler secret put MIMO_API_KEY\nnpx wrangler secret put SILICONFLOW_API_KEY\nnpm run deploy\n```\n\nThen build the frontend with:\n\n```bash\nVITE_POLARIS_API_ORIGIN=https://your-worker.example.com npm run build\n```\n\nThe Worker currently exposes a compact chat-completions shape. Provider relay,\nembeddings, image relay, search, diagnostics, and shared-material routes remain\nseparate backend responsibilities.\n\n## Android Build\n\nBuild and sync the web assets into the Android wrapper:\n\n```bash\nnpm i\nnpm run android:sync\n```\n\nBuild a debug APK for local testing:\n\n```bash\nnpm run android:build-debug\n```\n\nThe debug APK is generated under:\n\n```text\nandroid/app/build/outputs/apk/debug/\n```\n\nFor a release build:\n\n```bash\nnpm run android:build-release\n```\n\nPublic distribution uses a package identity, versioning, and signing setup owned\nby the distributor. Fork distributors normally use their own Android\n`applicationId`, Capacitor `appId`, app name, and versioning so their releases do\nnot collide with another channel.\n\nFor native builds that need internal `/api` routes, set\n`VITE_POLARIS_API_ORIGIN` to a deployer-owned backend during the build.\n\n## iOS Build\n\nSync the web assets into the iOS wrapper:\n\n```bash\nnpm i\nnpm run ios:sync\n```\n\nBuild for simulator without code signing:\n\n```bash\nnpm run ios:build-sim\n```\n\nBuild for device without App Store signing:\n\n```bash\nnpm run ios:build-device\n```\n\nTestFlight or App Store distribution requires an Apple Developer account,\nsigning identities, provisioning profiles, and capability review for the\ndistributor's own bundle identifier.\n\nFor native builds that need internal `/api` routes, set\n`VITE_POLARIS_API_ORIGIN` to a deployer-owned backend during the build.\n\n## Verification\n\nRun source checks before deploying:\n\n```bash\nnpm run typecheck\nnpm run test:data-boundary\nnpm test\nnpm run build\n```\n\nFor a broader source gate:\n\n```bash\nnpm run verify\n```\n\nFor publication hygiene:\n\n```bash\nnpm run publication:hygiene\n```\n\n## Troubleshooting\n\n`Failed to fetch` usually means the frontend is calling an API route that is not\navailable from the current origin. Deploy same-origin `/api` routes or rebuild\nwith `VITE_POLARIS_API_ORIGIN` set to a reachable backend.\n\n`404` on `/api/...` during `npm run dev` means Vite has no proxy target. Set\n`VITE_POLARIS_API_ORIGIN` in `.env.local` or run a host that serves the handlers.\n\nCORS errors mean the backend has not allowed the frontend origin. Add the exact\nfrontend origin to the backend allowlist instead of opening credentialed routes\nto every origin.\n\nAndroid installation blocks are controlled by the device. Enable installation\nfrom the browser or file manager used to open the APK.\n\nNative builds that show API failures need a real backend origin. A Capacitor app\nshell is not a backend server.\n\n## User Data\n\nPolaris is local-first. Browser data, Android data, iOS data, imported backups,\nand exported archives remain user-controlled local data unless a user explicitly\nexports, imports, or connects a backend.\n\nA self-hosted backend is not automatically a private data vault. The operator of\nthat backend can access the requests routed through it.\n\nPublic issues are safest with symptoms, versions, devices, and reproduction\nsteps instead of private backups, full databases, API keys, or chat exports.\n"}}}} |