June 12, 2026

Local Development and Deployment Tradeoffs for an AI Prototype

Notes on Deep Research's real local development, Docker, Supabase, and GitHub Actions deployment tradeoffs.

Deep Research is not just a demo page. Its README already includes local development, Docker hot reload, production builds, server deployment, and GitHub Actions automation. That makes it a product prototype meant to keep evolving.

For AI products, the hard part is often not the model call itself. The surrounding engineering matters just as much: auth, storage, task state, deployment, environment variables, observability, and rollback. If those layers are unstable, the agent workflow will not be reliable enough for long-term use.

Local Development

The project splits development into frontend and backend:

the backend is FastAPI on Python 3.11+, started locally with uvicorn main:app --reload --port 8000;
the frontend is Next.js and runs with pnpm;
storage can start as local JSON and later switch to Supabase;
LangGraph checkpoints can be persisted in Supabase Postgres;
multi-worker research jobs can move from an in-process queue to Redis Streams.

This split is practical. Early development can stay simple with JSON and an in-process queue, then Supabase, Redis, and Langfuse can be enabled as the product needs them.

Deployment Path

The project keeps Docker Compose and GitHub Actions deployment. In production, frontend and backend code are synced to the server, then images are rebuilt and containers are restarted.

I like this kind of explicit deployment path because it exposes problems that are invisible in local-only demos:

NEXT_PUBLIC_* values are bundled into the browser and cannot contain secrets.
OAuth callback paths and base paths must be decided before building.
API URL, frontend URL, Nginx reverse proxy, and health checks need to be verified together.
Model keys, Supabase service keys, and deploy keys must never enter the repository.

For an AI app to move beyond a demo, engineering stability is not optional. It decides whether research jobs finish, whether user data stays isolated, and whether failures can be diagnosed.

Deep Research 不是只写一个 demo 页面就结束的项目。README 里已经包含了本地开发、Docker 热更新、生产构建、服务器部署和 GitHub Actions 自动部署流程，这说明它的目标是一个可以持续迭代的 AI research 产品原型。

AI 产品的难点经常不在模型调用本身，而在周边工程：登录、存储、任务状态、部署、环境变量、观测和回滚。只要这些部分不稳定，agent 工作流再漂亮也很难长期使用。

本地开发

项目本地开发分成前后端：

后端是 FastAPI，使用 Python 3.11+，本地通过 uvicorn main:app --reload --port 8000 启动；
前端是 Next.js，使用 pnpm 启动；
存储可以先用本地 JSON，也可以切换到 Supabase；
LangGraph checkpoint 如果要持久化，可以接 Supabase Postgres；
多 worker 研究任务可以从进程内队列切到 Redis Streams。

这个分层比较实用：早期可以用 JSON 和本地进程队列降低复杂度，后面再把 Supabase、Redis、Langfuse 这些能力逐步打开。

部署链路

项目保留了 Docker Compose 和 GitHub Actions 自动部署。生产环境里，前端和后端分别同步到服务器目录，再重新构建镜像并启动容器。

真实项目里我更喜欢这种明确的部署路径，因为它能暴露很多“只在本地好用”的问题：

NEXT_PUBLIC_* 会进入浏览器 bundle，不能放密钥。
OAuth 回调路径和 base path 必须在构建时就想清楚。
API 地址、前端地址、Nginx 反代和健康检查要一起验证。
模型 key、Supabase service key、部署私钥都不能进入仓库。

AI 应用要从 demo 走向可用，工程稳定性不是附加项。它决定了研究任务能不能跑完、用户数据能不能隔离、失败时能不能定位问题。