PROD-8165 add extension development/deployment documentation

astro.sidebar.ts

@@ -580,6 +580,16 @@ const apisAndSdksItems = (prefix: string) => [
 			`${prefix}/reference/python-client`,
 		],
 	},
+	{
+		label: 'Extensions',
+		collapsed: true,
+		items: [
+			`${prefix}/reference/extensions/overview`,
+			`${prefix}/reference/extensions/quickstart`,
+			`${prefix}/reference/extensions/architecture`,
+			`${prefix}/reference/extensions/development-workflow`,
+		],
+	},
 	{
 		label: 'Mobile',
 		collapsed: true,
@@ -1784,6 +1794,7 @@ const mainSidebarItems = (
 				items: [
 					`${prefix}/user-guide/cli`,
 					`${prefix}/user-guide/cli-solutions`,
+					`${prefix}/user-guide/cli-extensions`,
 				],
 			},
 			`${prefix}/user-guide/ai-solution-creator`,
@@ -2198,6 +2209,7 @@ export const paasSidebar: SidebarConfig = [
 				items: [
 					'docs/paas/user-guide/cli',
 					'docs/paas/user-guide/cli-solutions',
+					'docs/paas/user-guide/cli-extensions',
 				],
 			},
 			'docs/paas/user-guide/ai-solution-creator',
@@ -2597,6 +2609,7 @@ export const paasEuSidebar: SidebarConfig = [
 				items: [
 					'docs/paas/eu/user-guide/cli',
 					'docs/paas/eu/user-guide/cli-solutions',
+					'docs/paas/eu/user-guide/cli-extensions',
 				],
 			},
 			'docs/paas/eu/user-guide/ai-solution-creator',

public/_redirects

@@ -101,6 +101,10 @@
 /docs/user-guide/install/pe/edge/windows/ /docs/edge/pe/installation/docker-windows/ 301
 
 # Single page redirects
+/docs/reference/extensions/cli-deployment/ /docs/user-guide/cli-extensions/ 301
+/docs/pe/reference/extensions/cli-deployment/ /docs/pe/user-guide/cli-extensions/ 301
+/docs/paas/reference/extensions/cli-deployment/ /docs/paas/user-guide/cli-extensions/ 301
+/docs/paas/eu/reference/extensions/cli-deployment/ /docs/paas/eu/user-guide/cli-extensions/ 301
 /docs/iot-gateway/configuration/ /docs/iot-gateway/config/general/ 301
 /docs/iot-gateway/how-device-removing-renaming-works/ /docs/iot-gateway/features/device-renaming/ 301
 /docs/iot-gateway/guides/how-to-configure-gateway-using-configurator/ /docs/iot-gateway/config/general/ 301

public/redirects.json

@@ -226,6 +226,10 @@
   "/docs/user-guide/install/pe/edge/rpi/": "/docs/edge/pe/installation/rpi/",
   "/docs/user-guide/install/pe/edge/upgrade-instructions/": "/docs/edge/pe/installation/upgrade-instructions/",
   "/docs/user-guide/install/pe/edge/windows/": "/docs/edge/pe/installation/docker-windows/",
+  "/docs/reference/extensions/cli-deployment/": "/docs/user-guide/cli-extensions/",
+  "/docs/pe/reference/extensions/cli-deployment/": "/docs/pe/user-guide/cli-extensions/",
+  "/docs/paas/reference/extensions/cli-deployment/": "/docs/paas/user-guide/cli-extensions/",
+  "/docs/paas/eu/reference/extensions/cli-deployment/": "/docs/paas/eu/user-guide/cli-extensions/",
   "/docs/iot-gateway/configuration/": "/docs/iot-gateway/config/general/",
   "/docs/iot-gateway/how-device-removing-renaming-works/": "/docs/iot-gateway/features/device-renaming/",
   "/docs/iot-gateway/guides/how-to-configure-gateway-using-configurator/": "/docs/iot-gateway/config/general/",

src/content/_includes/docs/reference/apis-and-sdks.mdx

@@ -48,6 +48,14 @@ import DocLink from '@components/DocLink.astro';
     - <DocLink product={props.product} path='reference/java-client' bold={false}>Java REST Client</DocLink>
     - <DocLink product={props.product} path='reference/python-client' bold={false}>Python REST Client</DocLink>
   </ListCard>
+
+  <ListCard headingLevel={3} title="Extensions" icon="puzzle">
+    - <DocLink product={props.product} path='reference/extensions/overview' bold={false}>Overview</DocLink>
+    - <DocLink product={props.product} path='reference/extensions/quickstart' bold={false}>Quickstart</DocLink>
+    - <DocLink product={props.product} path='reference/extensions/architecture' bold={false}>Architecture</DocLink>
+    - <DocLink product={props.product} path='reference/extensions/development-workflow' bold={false}>Development workflow</DocLink>
+    - <DocLink product={props.product} path='user-guide/cli-extensions' bold={false}>Deploy with the CLI</DocLink>
+  </ListCard>
 </CardGrid>
 
 ## Mobile apps

src/content/_includes/docs/reference/extensions/overview.mdx

@@ -0,0 +1,104 @@
+import { Aside } from '@astrojs/starlight/components';
+import DocLink from '@components/DocLink.astro';
+import ImageGallery from '@components/ImageGallery.astro';
+import Banner from '~/components/Banner.astro';
+import { Products } from '~/models/site.models';
+import ShowFor from '@components/ShowFor.astro';
+
+<Banner variant="peFeature" product={props.product}>Extensions work only with <DocLink product={Products.PE} path="reference/extensions/overview" target="_blank">ThingsBoard Professional</DocLink> and <a href="/installations/?product=thingsboard-cloud" target="_blank" rel="noopener noreferrer" class="tb-banner-ext"><b>ThingsBoard Cloud</b></a> version **4.4.0** or later.</Banner>
+
+{props.product !== Products.CE && (
+  <Banner variant="cloud">Available from ThingsBoard PE/Cloud <strong>4.4.0</strong> and later.</Banner>
+)}
+
+A **ThingsBoard extension** is a small service that adds your own REST API to a tenant. You write it in **Java** or **Python**, package it as a Docker image, and ThingsBoard runs it next to the platform.
+
+Clients never call your container directly. They call ThingsBoard at a fixed path:
+
+```text
+{BASE_URL}/api/extension/route/{slug}/…
+```
+
+ThingsBoard checks the caller first and only then forwards the request to your code. A dashboard widget, a rule chain, or an outside script reaches your service with the same login your users already have.
+
+## When you need one
+
+Use an extension when the built-in features are not enough — for example:
+
+- **Rule chain callbacks** — react to device telemetry, entity changes, or alarms from a rule chain.
+- **Dashboard widget backends** — run custom logic when a user clicks a button on a dashboard.
+- **Scheduled jobs** — run a task on a timer that reads or writes ThingsBoard data.
+- **Custom integrations** — talk to a third-party system and expose the result as an API.
+- **Platform management** — bundle several ThingsBoard API calls into one business operation, such as giving a new user a whole set of access rights at once. The <DocLink product={props.product} path='reference/extensions/quickstart#complete-example-user-profiles'>User Profiles example</DocLink> does exactly this.
+
+## When you do not need one
+
+An extension is a service that you write, build, and keep up to date. Simpler tools already solve many tasks:
+
+- **A rule node.** Filtering, enrichment, and message transformation belong in a <DocLink product={props.product} path='user-guide/rule-engine'>rule chain</DocLink>. Start there.
+- **A REST API call node.** When the logic already runs in another system, call that system from the rule chain.
+- **A widget.** Small logic that only changes what a user sees can stay in the <DocLink product={props.product} path='user-guide/widgets'>dashboard widget</DocLink>.
+- **The platform REST API.** A script on your own server can already read and write ThingsBoard data through the <DocLink product={props.product} path='reference/rest-api'>REST API</DocLink>.
+
+Pick an extension when you need your own endpoint **inside** ThingsBoard, your own libraries, or code that must run close to the platform.
+
+## What you get
+
+- **A URL inside ThingsBoard.** Your service is served from the same origin as the UI and the REST API, so dashboards and rule chains can call it with a relative URL.
+- **Authentication for free on every incoming request.** When a caller — a dashboard widget, a rule chain, an outside script — reaches your endpoint, ThingsBoard has already checked the credential, and your code calls ThingsBoard back with that same caller's credential. No admin password lives inside the extension. Work with no caller behind it, such as a scheduled job, is the exception: it needs its own service credential, set once as an environment variable. See <DocLink product={props.product} path='reference/extensions/architecture#authentication'>Authentication</DocLink>.
+- **A managed container.** ThingsBoard pulls the image, starts the container, watches it, and restarts it if it fails. You pick the number of replicas and a resource size.
+- **Normal tooling.** It is an ordinary web service: your own dependencies, your own tests, your own release tags. Nothing has to be written in a ThingsBoard-specific way.
+
+## What it looks like
+
+Every extension is a tenant entity, like a device or an asset. You find them in the ThingsBoard UI under **Data processing → Extensions**:
+
+<ImageGallery images={[{ src: '/src/assets/images/reference/extensions/extensions-list.png', alt: 'The ThingsBoard Extensions page listing four deployed extensions with their route, state, Docker image and ready replicas', caption: 'Each deployed extension is a tenant entity with its own route, state, image and replica count. The Available resources line under the table is the tenant quota. The screenshot is from a self-hosted PE installation, where the route carries the bare slug.' }]} />
+
+Each row shows the route, the state, the image, and how many replicas are ready. Open a row to see the container settings, read the logs, or stop and start the service. The **Available resources** line under the table is your tenant quota: how much you already use, and how many extensions of each size you can still deploy.
+
+<ShowFor product={props.product} show={[Products.PE]}>
+  The quota comes from the <DocLink product={props.product} path="user-guide/tenant-profiles#extension-limits">tenant profile</DocLink>: a system administrator sets the number of extensions and the total CPU and memory. A tenant cannot change them.
+</ShowFor>
+<ShowFor product={props.product} show={[Products.PAAS, Products.PAAS_EU]}>
+  The quota comes from your plan. A tenant cannot change it.
+</ShowFor>
+
+## How it works in short
+
+1. **You build an image.** `tb extension new` creates a ready-to-run Java or Python project. You add your endpoints to it, and `tb extension build` turns the project into a Docker image.
+2. **You push and deploy it.** The image goes to a container registry. One `tb extension deploy` command creates the extension entity and asks ThingsBoard to run that image. The CLI is a thin wrapper over the platform's `/api/extension` endpoints, so a CI job can do the same with plain REST calls — they are part of the <DocLink product={props.product} path='reference/rest-api'>ThingsBoard REST API</DocLink>.
+3. **ThingsBoard runs the container.** It pulls the image, starts the replicas you asked for, watches them, and restarts them after a failure. You never manage the host.
+4. **Clients call it through ThingsBoard.** The router checks the caller, removes the route prefix, and passes the request to your service. Your code calls the platform back with the caller's own credential.
+
+The <DocLink product={props.product} path='reference/extensions/architecture'>Architecture</DocLink> page shows this flow step by step, with the three authentication modes.
+
+## Where extensions run
+
+The same image runs in three places:
+
+- **Public cloud — ThingsBoard Cloud.** Managed for you. Extension containers run in their own cluster, separate from the platform cluster.
+- **Private cloud — your own ThingsBoard PE.** Managed the same way, on your infrastructure. A system administrator picks the substrate: your Kubernetes cluster, in a separate zone next to ThingsBoard, or a single Docker host.
+- **Self-hosted.** You run the container yourself with Docker Compose and route the traffic to it.
+
+The <DocLink product={props.product} path='reference/extensions/architecture#where-extensions-run'>Architecture</DocLink> page compares the three modes in detail.
+
+## What you need to start
+
+- **ThingsBoard PE or Cloud, version 4.4.0 or later.** On ThingsBoard Cloud the feature is already on. On a PE installation, a system administrator turns it on first with the `TB_EXTENSIONS_MODE` setting.
+- **The <DocLink product={props.product} path='user-guide/cli'>ThingsBoard CLI</DocLink> and Docker.** The CLI creates the project, builds the image, and deploys it.
+- **A container registry** that ThingsBoard can pull from — Docker Hub, GitHub Container Registry, or a private one.
+- **An <DocLink product={props.product} path='user-guide/security/api-keys' useTbDocs>API key</DocLink> for your tenant**, so the CLI can talk to ThingsBoard.
+
+Your service only has to follow one rule: listen on port **8090**. The endpoints live at the service root, and the router adds the public `/api/extension/route/{slug}` prefix in front of them. The Java and Python starters do this already.
+
+<Aside type="tip">
+The fastest way to build and ship an extension is the <DocLink product={props.product} path='user-guide/cli'>ThingsBoard CLI</DocLink>. The <DocLink product={props.product} path='reference/extensions/quickstart'>Quickstart</DocLink> deploys a ready one in five minutes; the <DocLink product={props.product} path='reference/extensions/development-workflow'>Development workflow</DocLink> builds your own, in Java or Python.
+</Aside>
+
+## Next steps
+
+- <DocLink product={props.product} path='reference/extensions/quickstart'>Quickstart</DocLink> — deploy a complete, working extension with one command, watch it run, and read its code.
+- <DocLink product={props.product} path='reference/extensions/architecture'>Architecture</DocLink> — routing, authentication, and the three ways to run an extension.
+- <DocLink product={props.product} path='reference/extensions/development-workflow'>Development workflow</DocLink> — the full development loop: plan, code, test, deploy, and ship updates.
+- <DocLink product={props.product} path='user-guide/cli-extensions'>Deploy with the CLI</DocLink> — the `tb extension deploy` command reference.