PROD-8165 add extension development/deployment documentation

[ivbond]

ThingsBoard 4.4.0 adds extensions: a tenant can ship its own REST API as a Docker image, and ThingsBoard runs it next to the platform. The feature had no documentation. This PR writes it.

Five new pages, ~1 200 lines of content, published for four products (CE, PE, Cloud, Cloud EU):

Page	Answers
Extensions overview	What an extension is, and when not to build one
Quickstart	Deploy a real working extension in five minutes with one command
Architecture	How a request reaches your container, how callers are checked, where the container runs
Development workflow	Build your own: plan, write, test, deploy, ship updates
Deploy extensions with ThingsBoard CLI	Command reference for tb extension deploy and tb extension deployments

Nothing outside the extensions topic changes behaviour. Four existing pages get a link to the new section, and the CLI page is added under the ThingsBoard CLI group.

---

What it looks like

1. New section and how it is served

1. Product switcher. The same content is served for Community, Professional, and Cloud. Each product gets its own URL and its own base URL inside code samples.
2. New "Extensions" group in the sidebar with four pages, in reading order: overview → quickstart → architecture → development workflow.
3. Page contents on the right. The headings come from the shared include file, not from the page stub — a build plugin lifts them into the table of contents.

2. Architecture — how a request reaches the container

1. Clients never call the container. They call ThingsBoard at /api/extension/route/{slug}/…, on the same origin as the UI.
2. The router checks first, forwards second. It asks the platform GET /api/ext-auth whether this caller may use this slug. The check is fail-closed: no answer means no forwarding.
3. The extension container is a plain web service on port 8090. It never sees a rejected call, so it does not have to check tokens itself.

The page carries seven diagrams, each drawn twice for the light and the dark theme.

3. Architecture — the two private managed modes

1. A private installation has two modes, not one. Which one runs is a system setting, extensions.mode.
2. private-cloud — Kubernetes, the cluster ThingsBoard already runs in, extensions in their own namespace. Replicas work as asked.
3. docker-compose — one Docker host. It always runs one container whatever replica count you ask for, because a single host has no load balancer behind a container name. This is easy to hit and was worth stating plainly.

4. Quickstart — a real run, not a sketch

1. Real CLI output. The page shows the actual tb init demo transcript, so a reader can compare it with their own terminal.
2. A table of what the command did — seven steps, each with its result, so nothing the command changed on the instance is a surprise.
3. The slug note. The extension name and its slug are different things: ThingsBoard Cloud appends a random suffix. Every command and URL on the page uses $SLUG for it, and the page says where the real value is printed.

5. The CLI reference page

1. Placed under the ThingsBoard CLI group, next to the other CLI pages, not inside the extensions section — it is a command reference, and CLI users look for it there. The old URL redirects.
2. Deploy is the topic, and the page is the reference for tb extension deploy plus the deployments control commands.
3. The first note draws the line between the local dev loop (build / run / logs / stop, on your machine) and deploy (server-side, ThingsBoard keeps it running). Readers mixed these two up.

---

How it is built

Nothing new was invented; the PR follows the patterns the repo already uses.

Content is written once and served four times. The text lives in a shared include under src/content/_includes/. Each product gets a small stub page that imports the include and passes its product:

src/content/_includes/docs/reference/extensions/overview.mdx   ← the content (1 file)
src/content/docs/docs/reference/extensions/overview.mdx        ← CE stub (8 lines)
src/content/docs/docs/pe/…                                     ← PE stub
src/content/docs/docs/paas/…                                   ← Cloud stub
src/content/docs/docs/paas/eu/…                                ← Cloud EU stub

That is 5 includes and 20 stubs. A product difference is expressed inside the include — <Banner> for the edition note, <HostCode> so {BASE_URL} becomes the right host per product — never by copying the page.

Diagrams are hand-written SVG, in pairs. 7 diagrams × 2 themes = 14 files under src/assets/schemas/. 10 UI screenshots go under src/assets/images/reference/extensions/.

One page moved. The CLI reference went from reference/extensions/cli-deployment to user-guide/cli-extensions. Four entries were added to src/data/redirects.ts (one per product) and pnpm generate:redirects was run, so public/_redirects and public/redirects.json are regenerated and in sync.

Facts were checked against the source, not from memory. The slug suffix rule, the two private modes, the replica behaviour of docker-compose, and the arguments that tb extension deployments status accepts were each read out of the ThingsBoard PE and ThingsBoard CLI code before being written down.

Affected products

CE, PE, Cloud, and Cloud EU. All four get the same five pages. No other product is touched.

Related issues

• PROD-8165

Type of change

• New / updated documentation page (src/content/docs/**)
• Shared include file (src/content/_includes/**)
• Component, layout, or styling change (src/components/**, src/styles/**)
• Landing / use-case / case-study page (src/pages/**, src/data/**)
• Redirects (src/data/redirects.ts)
• Version bump / release (see release skill)
• Build, CI, scripts, or tooling
• Other (please describe)

Checklist

• pnpm check passes (Astro / TypeScript) — 626 files, 0 errors, 0 warnings
• pnpm lint:eslint passes
• pnpm lint:slugcheck passes
• pnpm lint:linkcheck passes locally — 4 523 pages, no link issues
• Renamed page has a redirect in src/data/redirects.ts, and pnpm generate:redirects was run (regenerated output verified to have no drift)
• No hardcoded versions — the only version in the text is the 4.4.0 floor ("available from"), which is a fixed fact and must not follow src/data/versions.ts
• Screenshots attached for visual changes

Known follow-up

Two UI screenshots (extensions-list.png, extension-details.png) were taken on a self-hosted PE running an older build of the demo extension image, so the image tag in them reads java-4.3.1.3.post1 while the text shows java-4.4.0. The captions now say the shot is from a self-hosted install and that the tag is that instance's own. Worth re-taking on a 4.4.0 instance before release.

[Copilot]

Pull request overview

Adds a new “Extensions” documentation section to the ThingsBoard docs site, including end-to-end guidance for building, deploying, and operating ThingsBoard extensions, and exposes that section in the Reference navigation.

Changes:

• Introduces new Extensions reference pages (overview, quickstart, dev workflow, CLI deploy reference, REST deployment API) for CE/PE/Cloud variants via shared _includes.
• Adds Extensions links to the “APIs & SDKs” reference landing include and to the generated sidebar navigation.
• Adds new extension-related schema diagrams (light/dark variants) used by the docs.

Reviewed changes

Copilot reviewed 27 out of 41 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/content/docs/docs/reference/extensions/quickstart.mdx	CE wrapper page for Extensions quickstart include
src/content/docs/docs/reference/extensions/overview.mdx	CE wrapper page for Extensions overview include
src/content/docs/docs/reference/extensions/development-workflow.mdx	CE wrapper page for development workflow include
src/content/docs/docs/reference/extensions/deployment-api.mdx	CE wrapper page for deployment API include
src/content/docs/docs/reference/extensions/cli-deployment.mdx	CE wrapper page for CLI deployment include
src/content/docs/docs/pe/reference/extensions/quickstart.mdx	PE wrapper page for Extensions quickstart include
src/content/docs/docs/pe/reference/extensions/overview.mdx	PE wrapper page for Extensions overview include
src/content/docs/docs/pe/reference/extensions/development-workflow.mdx	PE wrapper page for development workflow include
src/content/docs/docs/pe/reference/extensions/deployment-api.mdx	PE wrapper page for deployment API include
src/content/docs/docs/pe/reference/extensions/cli-deployment.mdx	PE wrapper page for CLI deployment include
src/content/docs/docs/paas/reference/extensions/quickstart.mdx	PaaS wrapper page for Extensions quickstart include
src/content/docs/docs/paas/reference/extensions/overview.mdx	PaaS wrapper page for Extensions overview include
src/content/docs/docs/paas/reference/extensions/development-workflow.mdx	PaaS wrapper page for development workflow include
src/content/docs/docs/paas/reference/extensions/deployment-api.mdx	PaaS wrapper page for deployment API include
src/content/docs/docs/paas/reference/extensions/cli-deployment.mdx	PaaS wrapper page for CLI deployment include
src/content/docs/docs/paas/eu/reference/extensions/quickstart.mdx	PaaS EU wrapper page for Extensions quickstart include
src/content/docs/docs/paas/eu/reference/extensions/overview.mdx	PaaS EU wrapper page for Extensions overview include
src/content/docs/docs/paas/eu/reference/extensions/development-workflow.mdx	PaaS EU wrapper page for development workflow include
src/content/docs/docs/paas/eu/reference/extensions/deployment-api.mdx	PaaS EU wrapper page for deployment API include
src/content/docs/docs/paas/eu/reference/extensions/cli-deployment.mdx	PaaS EU wrapper page for CLI deployment include
src/content/_includes/docs/reference/extensions/quickstart.mdx	Shared quickstart content (Java/Python tabs + CLI workflow)
src/content/_includes/docs/reference/extensions/overview.mdx	Shared overview content (architecture, routing/auth, lifecycle, run modes)
src/content/_includes/docs/reference/extensions/development-workflow.mdx	Shared “full loop” workflow guide content
src/content/_includes/docs/reference/extensions/deployment-api.mdx	Shared REST deployment API reference content
src/content/_includes/docs/reference/extensions/cli-deployment.mdx	Shared CLI deploy/reference content
src/content/_includes/docs/reference/apis-and-sdks.mdx	Adds an “Extensions” card/links to the reference landing include
src/assets/schemas/extension-mode-self-hosted.svg	New diagram asset used in Extensions overview (light)
src/assets/schemas/extension-mode-self-hosted-dark.svg	New diagram asset used in Extensions overview (dark)
src/assets/schemas/extension-lifecycle.svg	New diagram asset used in Extensions overview (light)
src/assets/schemas/extension-lifecycle-dark.svg	New diagram asset used in Extensions overview (dark)
astro.sidebar.ts	Adds “Extensions” group under APIs & SDKs sidebar section

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.