From f9a2fe4eff4fe0b5d575669d50b140cfb9ee94ec Mon Sep 17 00:00:00 2001 From: Alex Lee <3076438032@qq.com> Date: Wed, 20 May 2026 14:51:15 +0800 Subject: [PATCH 01/12] docs(devbox): add frontend project guide --- v1/frontend/AGENT.md | 60 +++++++++++++++++++ v1/frontend/DESIGN.md | 36 ++++++++++++ v1/frontend/PRODUCT.md | 36 ++++++++++++ v1/frontend/README.md | 30 +++++++++- v1/frontend/ROADMAP.md | 21 +++++++ v1/frontend/docs/architecture.md | 94 ++++++++++++++++++++++++++++++ v1/frontend/docs/ia.md | 40 +++++++++++++ v1/frontend/docs/references.md | 17 ++++++ v1/frontend/docs/runbook.md | 98 ++++++++++++++++++++++++++++++++ 9 files changed, 431 insertions(+), 1 deletion(-) create mode 100644 v1/frontend/AGENT.md create mode 100644 v1/frontend/DESIGN.md create mode 100644 v1/frontend/PRODUCT.md create mode 100644 v1/frontend/ROADMAP.md create mode 100644 v1/frontend/docs/architecture.md create mode 100644 v1/frontend/docs/ia.md create mode 100644 v1/frontend/docs/references.md create mode 100644 v1/frontend/docs/runbook.md diff --git a/v1/frontend/AGENT.md b/v1/frontend/AGENT.md new file mode 100644 index 0000000..b11d0f5 --- /dev/null +++ b/v1/frontend/AGENT.md @@ -0,0 +1,60 @@ +# Devbox Provider Agent Notes + +## Scope + +This directory is the Devbox provider in the Sealos frontend workspace. It owns +the DevBox list, create/edit flow, detail page, template conversion UI, release +and deployment actions, and provider-side API routes under `app/api`. + +## Working Rules + +- Keep changes scoped to `frontend/providers/devbox` unless the task clearly + crosses a shared package boundary. +- Do not execute database writes or migrations unless the user explicitly asks. +- For production or test cloud images, build `linux/amd64` by default. +- For 70-cluster work, use `KUBECONFIG=/Users/mlhiter/.kube/70` and namespace + `devbox-frontend` unless the user gives a different target. +- The deployed image path uses the monorepo root `frontend/Dockerfile` with + `--build-arg name=devbox --build-arg path=providers/devbox`. +- The deployment has both `devbox-frontend-init` and `devbox-frontend` + containers. Inspect both image tags when verifying a rollout. +- Use the Codex in-app Browser for local browser verification. + +## Verification + +```bash +pnpm ts-lint +git diff --check +``` + +The package has no `test` script as of 2026-05-19, so generic test autodetection +that runs `npm test` will fail. Do not report that as a product regression; call +out the missing test script separately. + +## Important Paths + +- `app/[lang]/(platform)/(home)/page.tsx` - DevBox list entry. +- `app/[lang]/(platform)/devbox/create/page.tsx` - create/edit page shell. +- `app/[lang]/(platform)/devbox/create/components/Network.tsx` - network form, + public domain toggle, and custom domain drawer entry. +- `components/drawers/CustomAccessDrawer.tsx` - custom domain verification UX. +- `app/api/platform/authCname/route.ts` - CNAME verification endpoint. +- `app/api/platform/authDomainChallenge/route.ts` - fallback ownership + challenge verification endpoint. +- `utils/json2Yaml.ts` - form-to-Kubernetes manifest generation. +- `services/backend/kubernetes.ts` - Kubernetes client setup. +- `services/request.ts` - frontend request wrapper and auth headers. +- `services/db/init.ts` - Prisma client routing by `DATABASE_PROVIDER`. + +## Custom Domain Notes + +Custom domain verification first checks CNAME via `/api/platform/authCname`. +If that fails, it tries `/api/platform/authDomainChallenge`. A successful drawer +verification only updates the form field; the user still needs to click the +outer `update`/`变更` button to save the network configuration. + +For issue `labring-sigs/sealos-issues#171`, the reported "click confirm and +nothing happens" path was caused by dynamic DNS errors such as +`queryCname ENOTFOUND ` being treated as translation keys. Keep dynamic +DNS errors out of `next-intl` lookup paths; map known DNS codes to stable i18n +keys and show unknown messages as plain text. diff --git a/v1/frontend/DESIGN.md b/v1/frontend/DESIGN.md new file mode 100644 index 0000000..2fbb86f --- /dev/null +++ b/v1/frontend/DESIGN.md @@ -0,0 +1,36 @@ +# Devbox Design Notes + +Devbox is an operational product surface, not a marketing page. The interface +should be compact, predictable, and optimized for repeated configuration and +inspection. + +## UI Principles + +- Preserve the existing card and form structure when tuning layout. Prefer small + spacing and sizing improvements over broad redesigns. +- Keep status values in English unless the task explicitly asks for localization. +- Use concrete feedback for asynchronous actions. A button that validates or + mutates state must show loading, success, and failure states. +- Error copy should explain what the user can do next. Raw infrastructure + errors can appear only as fallback detail, not as the primary message. +- Keep dense configuration controls aligned and stable. Labels, buttons, and + dynamic text should not resize the surrounding network/resource form rows. +- Use `sonner` toasts for current provider UI feedback unless a component is + already bound to a different established local pattern. + +## Custom Domain UX + +The custom domain drawer is a validation step inside the larger DevBox edit +form. A successful validation does not persist the Kubernetes network change by +itself, so the success feedback must tell the user to save the outer form. + +DNS failure messages should use product language: + +- domain not found +- CNAME record missing +- CNAME target mismatch +- timeout +- network unreachable + +Avoid exposing raw `queryCname ENOTFOUND` or `queryCname ENODATA` as the only +visible explanation. diff --git a/v1/frontend/PRODUCT.md b/v1/frontend/PRODUCT.md new file mode 100644 index 0000000..c4c6501 --- /dev/null +++ b/v1/frontend/PRODUCT.md @@ -0,0 +1,36 @@ +# Devbox Product Context + +Devbox gives Sealos users a browser-managed development environment that can be +created from runtime templates, configured with resources and network access, +opened in IDEs, released, and deployed as an application. + +## Primary Users + +- Developers who need an on-demand cloud development environment. +- Template maintainers who convert existing DevBoxes into reusable templates. +- Platform operators who configure feature flags, runtime catalogs, pricing, + ingress domains, storage defaults, IDE availability, and database provider + settings for a region. + +## Core Jobs + +- Create a DevBox from a runtime/template with CPU, memory, GPU, storage, and + network settings. +- Open the DevBox in configured IDEs such as VS Code, Cursor, Web IDE, or other + enabled options. +- Edit an existing DevBox without rebuilding the mental model from YAML. +- Expose ports through generated public domains or user custom domains. +- Release a DevBox version and deploy it as an app. +- Convert a configured DevBox into a reusable template while reviewing + environment variables and ConfigMap defaults. + +## Product Boundaries + +- This provider owns the frontend and provider API surface. It does not own the + DevBox controller, runtime image internals, account service, monitor service, + registry service, or desktop shell. +- Provider-side changes can generate Kubernetes resources and patch existing + resources, but runtime behavior inside the user container belongs to the + runtime/controller layer. +- Database schema and migration execution must be explicit because this repo + supports both CockroachDB and PostgreSQL Prisma schemas. diff --git a/v1/frontend/README.md b/v1/frontend/README.md index 2aba0fb..425bc51 100644 --- a/v1/frontend/README.md +++ b/v1/frontend/README.md @@ -1,9 +1,16 @@ +# Devbox Frontend Provider + +Devbox is the Sealos frontend provider for creating, editing, releasing, and +operating DevBox development environments. It is a Next.js app inside the +Sealos frontend workspace. + ## How to dev 1. First,you should refer to `frontend/README.md` ’s `How to dev` part. 2. Then you should config your env. - 1. Create a new file `.env.local` in frontend/providers/kubepanel directory. + + 1. Create a new file `.env.local` in `frontend/providers/devbox`. > `SEALOS_DOMAIN` is anyone website you use in sealos. @@ -26,6 +33,7 @@ > Why you should have that? > > If you open your own dev in `localhost:3000` directly,you cannot have sealos desktop border,which maybe influence your style. + 1. This url：[website](https://cloud.sealos.run/?openapp=system-template%3FtemplateName%3Done-step-shortcuts) 2. ![image-20240423111024336](https://raw.githubusercontent.com/mlhiter/typora-images/master/202404231110609.png) @@ -35,3 +43,23 @@ 4. Then you can get your own dev in this. ![image-20240423111123308](https://raw.githubusercontent.com/mlhiter/typora-images/master/202404231111720.png) + +## Useful commands + +```bash +pnpm dev +pnpm build +pnpm ts-lint +pnpm gen-client +``` + +This workspace does not currently define a `test` script. Use `pnpm ts-lint` as +the focused typecheck until a real test command is added. + +## More docs + +- `AGENT.md` - agent operating notes for this provider. +- `docs/architecture.md` - module boundaries and request flow. +- `docs/runbook.md` - local verification and 70-cluster deployment notes. +- `docs/ia.md` - main pages and API route surfaces. +- `prisma/README.md` - Prisma schema and migration layout. diff --git a/v1/frontend/ROADMAP.md b/v1/frontend/ROADMAP.md new file mode 100644 index 0000000..56378e5 --- /dev/null +++ b/v1/frontend/ROADMAP.md @@ -0,0 +1,21 @@ +# Devbox Roadmap Notes + +This file tracks practical product/engineering gaps visible from the current +provider code. It is not a release commitment. + +## Near Term + +- Add regression coverage for custom-domain verification feedback so dynamic DNS + errors cannot be routed through i18n lookup again. +- Add a real package `test` script or document a project-level test command so + automated check scripts do not fail after typecheck. +- Keep template conversion defaults explicit and reviewable for environment + variables and ConfigMaps. + +## Operational Gaps + +- The current provider documentation is still lighter than the feature surface. + Keep `docs/architecture.md`, `docs/runbook.md`, and `docs/ia.md` updated as + future API or workflow changes land. +- ConfigMap single-file mounts use `subPath` for file shape. No-restart hot + updates require runtime/controller-level design, not only provider UI changes. diff --git a/v1/frontend/docs/architecture.md b/v1/frontend/docs/architecture.md new file mode 100644 index 0000000..267e8e1 --- /dev/null +++ b/v1/frontend/docs/architecture.md @@ -0,0 +1,94 @@ +# Devbox Provider Architecture + +## Overview + +Devbox is a Next.js provider application in the Sealos frontend workspace. It +combines React pages, provider API routes, Kubernetes clients, Prisma-backed +template storage, and shared Sealos UI packages. + +## Main Layers + +- `app/[lang]/(platform)/(home)` renders the DevBox list. +- `app/[lang]/(platform)/devbox/create` renders both create and edit flows. +- `app/[lang]/(platform)/devbox/detail/[name]` renders detail, network, release, + monitoring, logs, and sidebar surfaces for one DevBox. +- `components/` contains shared dialogs, drawers, IDE buttons, charts, and + template controls. +- `stores/` contains Zustand stores for DevBox, env, runtime, IDE, price, guide, + and related frontend state. +- `api/` contains browser-side request wrappers. +- `app/api/` contains Next.js route handlers that talk to Kubernetes, Prisma, + account, monitor, retag, and platform services. +- `utils/json2Yaml.ts` converts Devbox form data into Kubernetes manifests. +- `services/backend/kubernetes.ts` prepares Kubernetes clients from the current + session. +- `services/db/init.ts` selects the Prisma client according to + `DATABASE_PROVIDER`. + +## Network And Custom Domain Flow + +The create/edit network form lives in +`app/[lang]/(platform)/devbox/create/components/Network.tsx`. + +When public access is enabled, the form stores: + +- `networkName` +- `portName` +- `port` +- `protocol` +- `openPublicDomain` +- `publicDomain` +- `customDomain` + +The custom domain drawer validates ownership before writing `customDomain` into +the form. It does not persist Kubernetes state directly. + +Validation order: + +1. `components/drawers/CustomAccessDrawer.tsx` calls + `/api/platform/authCname`. +2. `app/api/platform/authCname/route.ts` verifies that the custom domain has a + CNAME pointing at the generated public domain. +3. If CNAME verification fails, the drawer calls + `/api/platform/authDomainChallenge`. +4. `app/api/platform/authDomainChallenge/route.ts` verifies the challenge + response exposed by the custom domain. +5. If either verification path succeeds, the drawer updates the form. The user + must still submit the outer edit form to update Kubernetes resources. + +## API Surface + +Legacy provider routes under `app/api` handle UI operations such as: + +- `getDevboxList`, `getDevboxByName`, `getDevboxPorts` +- `createDevbox`, `updateDevbox`, `updateDevboxWithoutYaml` +- `startDevbox`, `shutdownDevbox`, `restartDevbox`, `delDevbox` +- `releaseDevbox`, `releaseAndDeployDevbox` +- `templateRepository/*` +- `platform/*` +- `monitor/getMonitorData` + +Versioned API routes also exist under `app/api/v1` and `app/api/v2alpha`. +OpenAPI documentation is served through `app/api/openapi/route.ts` and +`app/api/v2alpha/openapi/route.ts`. + +## Data Model + +Template repository data uses Prisma. There is intentionally no default +`prisma/schema.prisma`; see `prisma/README.md`. + +Runtime client routing: + +- `DATABASE_PROVIDER=cockroachdb` uses `prisma/cockroach/schema.prisma` +- `DATABASE_PROVIDER=postgresql` uses `prisma/postgresql/schema.prisma` + +## Deployment Shape + +The deployed workload is `deployment/devbox-frontend` in namespace +`devbox-frontend`. It includes: + +- init container `devbox-frontend-init` for Prisma migration deployment +- main container `devbox-frontend` for the Next.js app +- service `devbox-frontend` +- ingress `devbox.` +- challenge ingress for `/.well-known/devbox-domain-challenge` diff --git a/v1/frontend/docs/ia.md b/v1/frontend/docs/ia.md new file mode 100644 index 0000000..eabf4c4 --- /dev/null +++ b/v1/frontend/docs/ia.md @@ -0,0 +1,40 @@ +# Devbox Information Architecture + +## Primary Pages + +- `/[lang]` - DevBox list/home page. +- `/[lang]/devbox/create` - create form. +- `/[lang]/devbox/create?name=&scrollTo=network` - edit form focused on + network configuration. +- `/[lang]/devbox/detail/[name]` - DevBox detail page. +- `/[lang]/template` - template management page. +- `/api-docs` - API docs surface. +- `/api/v2alpha/docs` - v2alpha API docs surface. + +## Main User Flows + +- List DevBoxes -> create DevBox -> open IDE. +- Detail page -> manage network -> edit form -> custom domain drawer -> submit + outer update. +- Detail page -> release -> deploy app. +- Detail page/template UI -> convert or update template. +- Import from Git or local archive when import features are enabled. + +## Major API Groups + +- DevBox CRUD and lifecycle: `getDevboxList`, `getDevboxByName`, + `createDevbox`, `updateDevbox`, `startDevbox`, `shutdownDevbox`, + `restartDevbox`, `delDevbox`. +- Network and access: `getDevboxPorts`, `updateDevboxWebIDEPort`, + `platform/authCname`, `platform/authDomainChallenge`, `checkReady`. +- Release and deployment: `releaseDevbox`, `releaseAndDeployDevbox`, + `deployDevbox`. +- Templates: `templateRepository/*`. +- Platform support: `platform/getQuota`, `platform/getDebt`, + `platform/resourcePrice`, guide routes, monitor routes, OpenAPI routes. + +## Navigation Notes + +The detail page network card has a `manage` action that routes to the create/edit +page with `scrollTo=network`. Network edits are made in the form page, not inside +the detail card itself. diff --git a/v1/frontend/docs/references.md b/v1/frontend/docs/references.md new file mode 100644 index 0000000..752f920 --- /dev/null +++ b/v1/frontend/docs/references.md @@ -0,0 +1,17 @@ +# Devbox References + +## Internal References + +- `frontend/README.md` - frontend workspace setup. +- `frontend/providers/devbox/prisma/README.md` - Prisma schema layout. +- `frontend/providers/devbox/.env.template` - environment variable template. +- `frontend/providers/devbox/deploy/manifests/deploy.yaml.tmpl` - deployment and + migration container shape. +- `frontend/providers/devbox/deploy/manifests/ingress.yaml.tmpl` - frontend and + domain-challenge ingress shape. + +## Issue References + +- `labring-sigs/sealos-issues#171` - custom domain drawer appeared to do nothing + when DNS validation failed. The fix maps dynamic DNS errors to stable UI copy + and avoids sending raw DNS strings through `next-intl`. diff --git a/v1/frontend/docs/runbook.md b/v1/frontend/docs/runbook.md new file mode 100644 index 0000000..90ea771 --- /dev/null +++ b/v1/frontend/docs/runbook.md @@ -0,0 +1,98 @@ +# Devbox Provider Runbook + +## Local Setup + +Start from the frontend workspace setup in `frontend/README.md`, then create a +provider env file: + +```bash +cd /Users/mlhiter/labring/sealos/frontend/providers/devbox +cp .env.template .env.local +``` + +Set at least: + +```bash +NEXT_PUBLIC_MOCK_USER='' +SEALOS_DOMAIN='192.168.10.70.nip.io' +INGRESS_DOMAIN='192.168.10.70.nip.io' +REGISTRY_ADDR='hub.192.168.10.70.nip.io' +JWT_SECRET='' +REGION_UID='' +DATABASE_URL='