Merge pull request #16290 from benja-M-1/extension/extract-validate

Extract the validation in its own page

_data/toc.yaml

@@ -1179,18 +1179,12 @@ manuals:
           title: Quickstart
         - sectiontitle: "Part one: Build"
           section:
-            - sectiontitle: "Step one: Create a new extension"
-              section:
-                - title: Create a simple extension
-                  path: /desktop/extensions-sdk/build/set-up/minimal-frontend-extension/
-                - title: Create a more advanced frontend
-                  path: /desktop/extensions-sdk/build/set-up/frontend-extension-tutorial/
-                - title: Add a backend to your extension
-                  path: /desktop/extensions-sdk/build/set-up/backend-extension-tutorial/
-            - title: "Step two: Build and install"
-              path: /desktop/extensions-sdk/build/build-install/
-            - title: "Step three: Test and debug"
-              path: /desktop/extensions-sdk/build/test-debug/
+            - title: Create a simple extension
+              path: /desktop/extensions-sdk/build/minimal-frontend-extension/
+            - title: Create a more advanced frontend
+              path: /desktop/extensions-sdk/build/frontend-extension-tutorial/
+            - title: Add a backend to your extension
+              path: /desktop/extensions-sdk/build/backend-extension-tutorial/
         - sectiontitle: "Part two: Publish"
           section:
             - title: Overview
@@ -1233,6 +1227,8 @@ manuals:
               path: /desktop/extensions-sdk/guides/oauth2-flow/
         - sectiontitle: Developer SDK tools
           section:
+            - title: "Test and debug"
+              path: /desktop/extensions-sdk/dev/test-debug/
             - title: CLI reference
               path: /desktop/extensions-sdk/dev/usage/
             - sectiontitle: Extension APIs

desktop/extensions-sdk/architecture/index.md

@@ -39,7 +39,7 @@ deployed on the host, through the [Extensions SDK](https://www.npmjs.com/package
 > vanilla Javascript.
 {: .tip }
 
-Learn more about [building a frontend](../build/set-up/frontend-extension-tutorial.md) for your extension.
+Learn more about [building a frontend](../build/frontend-extension-tutorial.md) for your extension.
 
 ## The backend
 
@@ -83,7 +83,7 @@ running Docker Desktop in constrained environments where they can't open ports o
 
 Finally, the backend can be built with any technology, as long as it can run in a container and listen on a socket.
 
-Learn more about [adding a backend](../build/set-up/backend-extension-tutorial.md) to your extension.
+Learn more about [adding a backend](../build/backend-extension-tutorial.md) to your extension.
 
 ## Executables
 

desktop/extensions-sdk/build/backend-extension-tutorial.md

@@ -5,6 +5,7 @@ keywords: Docker, extensions, sdk, build
 redirect_from:
   - /desktop/extensions-sdk/tutorials/minimal-backend-extension/
   - /desktop/extensions-sdk/build/minimal-backend-extension/
+  - /desktop/extensions-sdk/build/set-up/backend-extension-tutorial/
 ---
 
 Your extension can ship a backend part with which the frontend can interact with. This page provides information on
@@ -16,7 +17,7 @@ why and how to add a backend.
 
 > Note
 >
-> If you want to start a codebase for your new extension, our [Quickstart guide](../../quickstart.md) and `docker extension init <my-extension>` provides a better base for your extension as it is more up-to-date and related to your install of Docker Desktop.
+> If you want to start a codebase for your new extension, our [Quickstart guide](../quickstart.md) and `docker extension init <my-extension>` provides a better base for your extension as it is more up-to-date and related to your install of Docker Desktop.
 
 ## Why add a backend?
 
@@ -29,7 +30,7 @@ builders have used the backend to:
 - Store the extension state, like when a button starts a long-running process, so that if you navigate away
   from the extension user interface and come back, the frontend can pick up where it left off.
 
-Learn more about extension backend in the [architecture](../../architecture/index.md#the-backend) section.
+Learn more about extension backend in the [architecture](../architecture/index.md#the-backend) section.
 
 ## Add a backend to the extension
 
@@ -306,7 +307,7 @@ in the `vm` section of the `metadata.json` file.
 }
 ```
 
-For more information on the `vm` section of the `metadata.json`, see [Metadata](../../architecture/metadata.md).
+For more information on the `vm` section of the `metadata.json`, see [Metadata](../architecture/metadata.md).
 
 > **Warning**
 >
@@ -418,7 +419,7 @@ when you need to debug it.
 >
 > You may need to enable the "Show system containers" option in Docker Desktop to see the backend container running
 > under the extension compose project in the containers tab of the dashboard.
-> See [how to show extension containers](../test-debug.md#show-the-extension-containers) for more information.
+> See [how to show extension containers](../dev/test-debug.md#show-the-extension-containers) for more information.
 {: .tip }
 
 Open Docker Desktop Dashboard and click on the containers tab. You should see the response from the backend service
@@ -426,5 +427,5 @@ call displayed.
 
 ## What's next?
 
-- Learn how to [share and publish your extension](../../extensions/index.md).
-- Learn more about extensions [architecture](../../architecture/index.md).
+- Learn how to [share and publish your extension](../extensions/index.md).
+- Learn more about extensions [architecture](../architecture/index.md).

desktop/extensions-sdk/build/frontend-extension-tutorial.md

@@ -6,6 +6,7 @@ redirect_from:
   - /desktop/extensions-sdk/tutorials/react-extension/
   - /desktop/extensions-sdk/build/set-up/react-extension/
   - /desktop/extensions-sdk/build/set-up/minimal-frontend-using-docker-cli/
+  - /desktop/extensions-sdk/build/set-up/frontend-extension-tutorial/
 ---
 
 To start creating your extension, you first need a directory with files which range from the extension’s source code to the required extension-specific files. This page provides information on how to set up a simple Docker extension that contains only a UI part.
@@ -17,7 +18,7 @@ To start creating your extension, you first need a directory with files which ra
 ## Extension folder structure
 
 The quickest way to create a new extension is to run `docker extension init my-extension` as in the
-[Quickstart](../../quickstart.md). This will create a new directory `my-extension` that contains a fully functional extension.
+[Quickstart](../quickstart.md). This will create a new directory `my-extension` that contains a fully functional extension.
 
 > **Tip**
 >
@@ -164,7 +165,7 @@ The `root` property is the path to the frontend application in the extension's c
 system to deploy it on the host.
 The `src` property is the path to the HTML entry point of the frontend application within the `root` folder.
 
-For more information on the `ui` section of hte `metadata.json`, see [Metadata](../../architecture/metadata.md#ui-section).
+For more information on the `ui` section of hte `metadata.json`, see [Metadata](../architecture/metadata.md#ui-section).
 
 ## Build the extension and install it
 
@@ -340,10 +341,34 @@ export function App() {
 
 ![Screenshot of the container list.](images/react-extension.png)
 
+## Re-build the extension and update it
+
+Since you have modified the code of the extension, you must build again the extension.
+
+```console
+$ docker build --tag= awesome-inc/my-extension:latest .
+```
+
+Once built, you need to update it.
+
+```console
+$ docker extension update awesome-inc/my-extension:latest
+```
+
+Now you can see the backend service running in the containers tab of the Docker Desktop Dashboard and watch the logs
+when you need to debug it.
+
+> **Tip**
+>
+> You can turn on [hot reloading](../dev/test-debug.md#hot-reloading-whilst-developing-the-ui) to avoid the need to
+> rebuild the extension every time you make a change.
+{: .tip }
+
 ## What's next?
 
-- Learn how to [build and install your extension](../build-install.md).
-- Learn more about extensions [architecture](../../architecture/index.md).
-- For more information and guidelines on building the UI, see the [Design and UI styling section](../../design/design-guidelines.md).
-- If you want to set up user authentication for the extension, see [Authentication](../../guides/oauth2-flow.md).
+- Add a [backend](./backend-extension-tutorial.md) to your extension.
+- Learn how to [test and debug](../dev/test-debug.md) your extension.
+- Learn more about extensions [architecture](../architecture/index.md).
+- For more information and guidelines on building the UI, see the [Design and UI styling section](../design/design-guidelines.md).
+- If you want to set up user authentication for the extension, see [Authentication](../guides/oauth2-flow.md).
 

desktop/extensions-sdk/build/minimal-frontend-extension.md

@@ -4,6 +4,7 @@ description: Minimal frontend extension tutorial
 keywords: Docker, extensions, sdk, build
 redirect_from:
   - /desktop/extensions-sdk/tutorials/minimal-frontend-extension/
+  - /desktop/extensions-sdk/build/set-up/minimal-frontend-extension/
 ---
 
 To start creating your extension, you first need a directory with files which range from the extension’s source code to the required extension-specific files. This page provides information on how to set up a minimal frontend extension based on plain HTML.
@@ -14,7 +15,7 @@ To start creating your extension, you first need a directory with files which ra
 
 > Note
 >
-> If you want to start a codebase for your new extension, our [Quickstart guide](../../quickstart.md) and `docker extension init <my-extension>` will provide a better base for your extension, more up-to-date and related to your install of Docker Desktop.
+> If you want to start a codebase for your new extension, our [Quickstart guide](../quickstart.md) and `docker extension init <my-extension>` will provide a better base for your extension, more up-to-date and related to your install of Docker Desktop.
 
 ## Extension folder structure
 
@@ -33,7 +34,7 @@ Although you can start from an empty directory, it is highly recommended that yo
 1. Contains everything required to build the extension and run it in Docker Desktop.
 2. A file that provides information about the extension such as the name, description, and version.
 3. The source folder that contains all your HTML, CSS and JS files. There can also be other static assets such as logos
-   and icons. For more information and guidelines on building the UI, see the [Design and UI styling section](../../design/design-guidelines.md).
+   and icons. For more information and guidelines on building the UI, see the [Design and UI styling section](../design/design-guidelines.md).
 
 ## Create a Dockerfile
 
@@ -47,9 +48,9 @@ At a minimum, your Dockerfile needs:
 # syntax=docker/dockerfile:1
 FROM scratch
 
-LABEL org.opencontainers.image.title="MinimalFrontEnd" \
+LABEL org.opencontainers.image.title="Minimal frontend" \
     org.opencontainers.image.description="A sample extension to show how easy it's to get started with Desktop Extensions." \
-    org.opencontainers.image.vendor="Docker Inc." \
+    org.opencontainers.image.vendor="Awesome Inc." \
     com.docker.desktop.extension.api.version="1.0.0-beta.1" \
     com.docker.desktop.extension.icon="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png"
 
@@ -65,7 +66,7 @@ A `metadata.json` file is required at the root of the image filesystem.
 {
   "ui": {
     "dashboard-tab": {
-      "title": "Min FrontEnd Extension",
+      "title": "Minimal frontend",
       "root": "/ui",
       "src": "index.html"
     }
@@ -73,10 +74,36 @@ A `metadata.json` file is required at the root of the image filesystem.
 }
 ```
 
-For more information on the `metadata.json`, see [Metadata](../../architecture/metadata.md).
+For more information on the `metadata.json`, see [Metadata](../architecture/metadata.md).
+
+## Build the extension and install it
+
+Now that you have configured the extension, you need to build the extension image that Docker Desktop will use to
+install it.
+
+```console
+$ docker build --tag= awesome-inc/my-extension:latest .
+```
+
+This built an image tagged `awesome-inc/my-extension:latest`, you can run `docker inspect
+awesome-inc/my-extension:latest` to see more details about it.
+
+Finally, you can install the extension and see it appearing in the Docker Desktop Dashboard.
+
+```console
+$ docker extension install awesome-inc/my-extension:latest
+```
+
+## Preview the extension
+
+To preview the extension in Docker Desktop, close and open Docker Dashboard once the installation is complete.
+
+The left-hand menu displays a new tab with the name of your extension.
+
+![minimal-frontend-extension](images/ui-minimal-extension.png)
 
 ## What's next?
 
-- Learn how to [build and install your extension](../build-install.md).
-- Learn more about extensions [architecture](../../architecture/index.md).
-- Build a more advanced frontend extension by following the [Advanced frontend extension tutorial](./frontend-extension-tutorial.md).
+- Build a more [advanced frontend](./frontend-extension-tutorial.md) extension.
+- Learn how to [test and debug](../dev/test-debug.md) your extension.
+- Learn more about extensions [architecture](../architecture/index.md).

desktop/extensions-sdk/dev/test-debug.md

@@ -1,19 +1,12 @@
 ---
-title: "Step three: Test and debug"
-description: Step four in the extension creation process
+title: "Test and debug"
+description: Test and debug your extension.
 keywords: Docker, Extensions, sdk, preview, update, Chrome DevTools
+redirect_from:
+- /desktop/extensions-sdk/build/test-debug/
 ---
 
-Once your extension has been [built and installed](build-install.md), you can preview your extension in Docker Desktop. 
-
-## Preview the extension
-
-To preview the extension in Docker Desktop, close and open Docker Dashboard once the installation is complete.
-
-The left-hand menu displays a new tab with the name of your extension. 
-The example below shows the [`Min FrontEnd Extension`](set-up/minimal-frontend-extension.md). 
-
-![minimal-frontend-extension](images/ui-minimal-extension.png)
+In order to improve the developer experience, Docker Desktop provides a set of tools to help you test and debug your extension.
 
 ### Open Chrome DevTools
 
@@ -66,14 +59,6 @@ If your extension is composed of one or more services running as containers in t
 2. Under the **Extensions** tab, select the **Show Docker Desktop Extensions system containers** option. You can now view your extension containers and their logs.
 
 
-## Update the extension
-
-To update the extension, you must first [rebuild and reinstall](build-install.md) your extension. You can then use the update command.
-
-```console
-$ docker extension update <name-of-your-extensions>
-```
-
 ## Clean up
 
 To remove the extension, run:
@@ -82,9 +67,8 @@ To remove the extension, run:
 $ docker extension rm <name-of-your-extension>
 ```
 
-## What's next?
+## What's next
 
-- Explore our [design principles](../design/design-principles.md).
-- Take a look at our [UI styling guidelines](../design/overview.md).
-- Set up [authentication for your extension](../guides/oauth2-flow.md)
-- Learn how to [publish your extension](../extensions/index.md).
+- Build an [advanced frontend](../build/frontend-extension-tutorial.md) extension.
+- Learn more about extensions [architecture](../architecture/index.md).
+- Learn more about [designing the UI](../design/design-guidelines.md).

desktop/extensions-sdk/extensions/index.md

@@ -13,8 +13,8 @@ You have developed your extension and tested it locally. You are now ready to re
 Releasing your extension consists of:
 
 - Provide information about your extension: description, screenshots, etc. so users can decide to install your extension
-- Validate the extension is built in the right format and includes the required information
-- Make the extension image available on [DockerHub](https://hub.docker.com/){: target="_blank" rel="noopener" class="_" }:
+- [Validate](./validate.md) the extension is built in the right format and includes the required information
+- Make the extension image available on [Docker Hub](https://hub.docker.com/){: target="_blank" rel="noopener" class="_" }:
 
 See [Package and release your extension](DISTRIBUTION.md) for details about the release process.
 

desktop/extensions-sdk/extensions/publish.md

@@ -20,7 +20,7 @@ These guidelines don't replace Docker's terms of service or guarantee approval.
 
 #### Guidelines:
 
-- Ensure that you’ve ran the [validation checks](../build/build-install.md)
+- Ensure that you’ve ran the [validation checks](validate.md)
 - Review the [design guidelines](../design/design-guidelines.md)
 - Ensure the [UI styling](../design/overview.md) is in line with Docker Desktop guidelines
 - Ensure your extensions support both light and dark mode

desktop/extensions-sdk/extensions/validate.md

@@ -1,23 +1,17 @@
 ---
-title: "Step two: Build and install"
+title: Validate your extension
 description: Step three in the extension creation process
 keywords: Docker, Extensions, sdk, validate, install
 redirect_from:
 - /desktop/extensions-sdk/extensions/validation/
+- /desktop/extensions-sdk/build/build-install/
 - /desktop/extensions-sdk/dev/cli/build-test-install-extension/
 ---
 
-Once you have set up your directory correctly, you can build your extension for single or multiple architectures. 
+Validate your extension before you share or publish it. Validating the extension ensures:
 
-## Build the extension for a single architecture
-
-To build the extension, run:
-
-```console
-$ docker build -t <name-of-your-extension> .
-```
-
-## Validate your extension
+- That the extension is built with the [image labels](labels.md) it requires to display correctly in the marketplace
+- That the extension installs and runs without problems
 
 The Extensions CLI lets you validate your extension before installing and running it locally.
 
@@ -43,27 +37,3 @@ $ docker extension validate /path/to/metadata.json
 
 The JSON schema used to validate the `metadata.json` file against can be found under the [releases page](https://github.com/docker/extensions-sdk/releases/latest){:target="_blank" rel="noopener" class="_"}.
 
-## Install the extension
-
-To install the extension in Docker Desktop, run:
-
-```console
-$ docker extension install <name-of-your-extension>
-```
-
-> Note 
-> 
-> Extensions can install binaries, invoke commands and access files on your machine. Make sure you trust extensions before installing them on your machine.
-
-To list all your installed extensions, run:
-
-```typescript
-$ docker extension ls
-
-ID                              PROVIDER            VERSION             UI                   VM                  HOST
-docker/hub-explorer-extension   Docker Inc.         0.0.2               1 tab(Explore Hub)   Running(1)          1 binarie(s)
-```
-
-## What's next?
-
-Learn how to [test and debug](test-debug.md) your extension.

desktop/extensions-sdk/index.md

@@ -16,7 +16,7 @@ Use the resources in this section to create your own Docker Extension.
 Extensions are packaged as specially formatted Docker images, which our CLI tool helps to build. At the root of the image filesystem is a `metadata.json` file which describes the content of the extension. It is a fundamental element of a Docker extension.
 
 An extension can contain a UI part and backend parts that run either on the host or in the Desktop virtual machine.
-For further details, see [Extension metadata](architecture/metadata.md).
+For further details, see the [architecture page](architecture/index.md).
 
 Extensions are distributed through the Docker Hub.
 Development of extensions can be done locally without the need to push the extension to Docker Hub. See [Extensions distribution](extensions/DISTRIBUTION.md) for further details.

desktop/extensions-sdk/process.md

@@ -15,23 +15,11 @@ The build process consists of:
 - Creating the Dockerfile to build, publish, and run your extension in Docker Desktop.
 - Configuring the metadata file which is required at the root of the image filesystem.
 - Building and installing the extension.
-- Testing and debugging the extension.
-
-There are also instructions on [how to set authentication](guides/oauth2-flow.md) for your extension.
-
-This build section provides sample folders with ready-to-go examples that walk you through building:
-
-- A frontend extension based on plain HTML
-- A simple Docker extension that contains only a UI part and is based on ReactJS. This is useful if you want to develop an extension which consists exclusively of a visual part with no services running in the VM.
-- An extension that invokes Docker CLI commands
-- A simple backend extension
 
 > Note
 >
 > Whilst you're building your extension, make sure you follow our [design](design/design-guidelines.md) and [UI styling](design/overview.md) guidelines to ensure visual consistency and [level AA accessibility standards](https://www.w3.org/WAI/WCAG2AA-Conformance){:target="_blank" rel="noopener" class="_"}.
 
-If your extension requires additional services running in the Docker Desktop VM, see the [VM UI](https://github.com/docker/extensions-sdk/tree/main/samples/vm-service){:target="_blank" rel="noopener" class="_"} example.
-
 For further inspiration, see the other examples in the [samples folder](https://github.com/docker/extensions-sdk/tree/main/samples){:target="_blank" rel="noopener" class="_"}.
 
 ### Part two: Publish and distribute your extension

desktop/extensions-sdk/quickstart.md

@@ -60,9 +60,13 @@ $ docker extension install <name-of-your-extension>
 
 To preview the extension in Docker Desktop, open Docker Dashboard once the installation is complete.
 
-During UI development, it’s helpful to use hot reloading to test your changes without rebuilding your entire extension. See [Preview whilst developing the UI](build/test-debug.md#hot-reloading-whilst-developing-the-ui) for more information.
+During UI development, it’s helpful to use hot reloading to test your changes without rebuilding your entire
+extension. See [Preview whilst developing the UI](dev/test-debug.md#hot-reloading-whilst-developing-the-ui) for more
+information.
 
-You may also want to inspect the containers that belong to the extension. By default, extension containers are hidden from the Docker Dashboard. You can change this in **Settings**, see [how to show extension containers](build/test-debug.md#show-the-extension-containers) for more information.
+You may also want to inspect the containers that belong to the extension. By default, extension containers are
+hidden from the Docker Dashboard. You can change this in **Settings**, see
+[how to show extension containers](dev/test-debug.md#show-the-extension-containers) for more information.
 
 ## Step four: Submit and publish your extension to the Marketplace
 
@@ -78,9 +82,7 @@ $ docker extension rm <name-of-your-extension>
 
 ## What's next
 
-Learn more about:
-
-- [Building and installing an extension](build/build-install.md)
-- [Testing and debugging](build/test-debug.md)
-- [Setting up authentication](guides/oauth2-flow.md)
-- [Designing the UI](design/design-guidelines.md)
+- Build a more [advanced frontend](build/frontend-extension-tutorial.md) for your extension.
+- Learn how to [test and debug](dev/test-debug.md) your extension.
+- Learn more about extensions [architecture](architecture/index.md).
+- Learn more about [designing the UI](design/design-guidelines.md).