docs(user-guide): add guide for bringing an application to codemie - #402
alex-budanov wants to merge 5 commits into
Conversation
Adds a plain-language guide for teams registering their own product as an application tile, covering the link/iframe/module choice, the YAML entry, what to test, and a pre-submission checklist. Also adds the Applications category to the user-guide sidebar, which was previously unreachable by navigation.
The audience line said "already built its own product", which excluded teams building a panel specifically for CodeMie. That is the reader the module type and the capability-reuse section serve, and the module example in the same page already addresses them.
…guidance Replaces the invented scenarios with AICE, MF Lens and Technology Copilot, named with their owning teams, plus one clearly labelled hypothetical for the link type. MF Lens also gives the co-deployment path its first real example. Capability reuse now leads with the pattern actually in production, a service key for CodeMie's LiteLLM proxy, rather than the same-origin module session that nothing currently relies on. The login paragraph said only that CodeMie passes no identity. It now says how to get single sign-on: register a client with the same identity provider the deployment uses.
The section promised three options and then presented a fourth thing in a bold paragraph. Co-deployment is orthogonal to the render type, not a fourth type, so the heading drops the count and co-deployment gets a subsection a reader can scan to. The cross-reference earlier in the page now resolves to a visible heading. Also renames "Real-world examples" to "Examples", since one of the four entries is a labelled hypothetical.
PR Preview Ready!Your preview documentation is ready! Visit it here: Preview URL: http://codemie-docs-pr-previews.s3-website.eu-central-1.amazonaws.com/pr-402/
This preview will be automatically updated when you push new commits to this PR. |
|
Superseded by #411, which includes a corrected version of this page (drops the unverifiable "AICE framed from CodeMie's own host" claim and the stale |
1 participant
Summary
Adds a user-guide page for teams that want their own product to appear as an application tile in CodeMie. Written for the team bringing the product, not for the operator: it covers whether an application tile is even the right mechanism, the
link/iframe/modulechoice, the YAML entry, what to test, and a pre-submission checklist.Replaces the approach in #396 (closed). That PR added a 330-line admin-side guide; this one is a shorter user-guide page, reviewed against the codebase and against a live deployment rather than written from the spec.
Changes
docs/user-guide/applications/add-an-application.md(~1,880 words)docs/user-guide/applications/index.mdto describe what an application is and link to the new guideindex.mdexisted but nothing pointed to it)SAMEORIGINandAIMFto the cspell dictionaryTesting
npm startVerified via
npm run build, which fails on broken links and unresolvable sidebar ids, and by inspecting the generated HTML. Not verified in a browser: no browser tooling in this repo, so layout was not visually reviewed. Checked on the built output instead: the 5-column table gets the theme'soverflow: auto, and the task-list checkboxes render as standard disabled inputs. No images on this page.Quality Checks
npm run checkpasses (typecheck + lint + commitlint)<text>must be`<text>`)static/img/)Additional Notes
Every behavioural claim was checked against
codemieandcodemie-ui, and the examples against the liveGET /v1/applicationson a running deployment. Corrections to the earlier draft:Applicationsentry, gated on at least one enabled app; each product is a tile on the page behind it. Confirmed visually against a live instance.descriptionis the tile's body text, not its subtitle. The subtitle isby <created_by>, and it is omitted whencreated_byis unset.url,nameandtypeall carry that blast radius, noturlalone.Examples are now the real registered applications (AICE, MF Lens, Technology Copilot) with their owning teams, plus one clearly labelled hypothetical for
link. MF Lens gives the co-deployment path its first real example.Open questions for the platform team, currently carried in the text as hedges rather than statements:
customer-config.yamlis a ConfigMap managed outside this repo. This is now confirmed empirically: the live application list differs from the one inconfig/customer/customer-config.yaml, with two repo entries absent and two live entries that exist nowhere in this repository. No owner or channel is named anywhere, so the page cannot name one.moduleruns on CodeMie's origin and can therefore call CodeMie's API as the signed-in user with nothing handed to it. Nothing registered today relies on this and it is not a documented contract. Whether it is intended needs an answer; if not, it is a security question rather than a feature.frame-ancestorstells iframe authors to name "CodeMie's host" without giving a value, because none is published in the chart or nginx config. Both live iframes sidestep this by being served from a path on CodeMie's own host; whether that routing is generally available to new teams is unclear.created_by: null, no deployment guide, and no mention anywhere in these repositories. It is a registered tile with no recorded owner, which is exactly what the checklist's "named owner" item exists to prevent.customer-config.yamlwould fail this guide's own checklist on all three entries: twohttp://localhostURLs, an unpinned entry, and two empty descriptions. Worth fixing as config hygiene, since it is the first thing anyone copies.Co-deployment is described and given a checklist but has no procedure; it may belong in a separate admin-side page.