From 4f59d8cafb1f5c9363291e6d8b34af2c46fe854c Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Mon, 24 Jul 2023 11:03:14 +0200 Subject: [PATCH] Review extensions quickstart (#17794) * Review extensions quickstart Signed-off-by: Chris Chinchilla Draft Signed-off-by: Chris Chinchilla Draft Signed-off-by: Chris Chinchilla * Update desktop/extensions-sdk/quickstart.md Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> --------- Signed-off-by: Chris Chinchilla Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> --- desktop/extensions-sdk/index.md | 12 ++++++++---- desktop/extensions-sdk/process.md | 26 +++++++++++++++----------- desktop/extensions-sdk/quickstart.md | 17 +++++++++-------- 3 files changed, 32 insertions(+), 23 deletions(-) diff --git a/desktop/extensions-sdk/index.md b/desktop/extensions-sdk/index.md index 266294d6f8..8432d413cf 100644 --- a/desktop/extensions-sdk/index.md +++ b/desktop/extensions-sdk/index.md @@ -6,18 +6,22 @@ redirect_from: - /desktop/extensions-sdk/dev/overview/ --- -Use the resources in this section to create your own Docker Extension. +The resources in this section help you 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. +The Docker CLI tool provides a set of commands to help you build and publish your extension, packaged as a +specially formatted Docker image. + +At the root of the image filesystem is a `metadata.json` file which describes the content of the extension. +It's 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 information, see [Architecture](architecture/index.md). -Extensions are distributed through Docker Hub. However, 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. +You distribute extensions through Docker Hub. However, you can develop them locally without the need to push +the extension to Docker Hub. See [Extensions distribution](extensions/DISTRIBUTION.md) for further details. {% include extensions-form.md %} -
diff --git a/desktop/extensions-sdk/process.md b/desktop/extensions-sdk/process.md index fc872d607f..b756ef790b 100644 --- a/desktop/extensions-sdk/process.md +++ b/desktop/extensions-sdk/process.md @@ -4,39 +4,43 @@ title: The build and publish process keyword: Docker Extensions, sdk, build, create, publish --- -The documentation is structured so that it matches the steps you need to take when creating your extension. There are two main parts to creating a Docker Extension; build the foundations and then publish your extension. +This documentation is structured so that it matches the steps you need to take when creating your extension. -### Part one: Build the foundations +There are two main parts to creating a Docker Extension: + +1. Build the foundations +2. Publish the extension + +## Part one: Build the foundations The build process consists of: - Installing the latest version of Docker Desktop. -- Setting up the directory with files which range from the extension’s source code to the required extension-specific files. -- Creating the Dockerfile to build, publish, and run your extension in Docker Desktop. +- Setting up the directory with files, including the extension’s source code and the required extension-specific files. +- 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. > Note > -> Whilst you're building your extension, make sure you follow our [design](design/design-guidelines.md) and [UI styling](design/index.md) guidelines to ensure visual consistency and [level AA accessibility standards](https://www.w3.org/WAI/WCAG2AA-Conformance){:target="_blank" rel="noopener" class="_"}. +> Whilst building your extension, make sure you follow the [design](design/design-guidelines.md) and [UI styling](design/index.md) guidelines to ensure visual consistency and [level AA accessibility standards](https://www.w3.org/WAI/WCAG2AA-Conformance){:target="_blank" rel="noopener" class="_"}. 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 +## Part two: Publish and distribute your extension Docker Desktop displays published extensions in the Extensions Marketplace. The Extensions Marketplace is a curated space where developers can discover extensions to improve their developer experience and upload their own extension to share with the world. -If you want your extension to be published in the Marketplace, see our [publish](./extensions/publish.md) -documentation page. +If you want your extension published in the Marketplace, read the [publish documentation](./extensions/publish.md). {% include extensions-form.md %} ## What’s next? -If you want to get up and running quickly with a Docker Extension, see the [Quickstart guide](quickstart.md). +If you want to get up and running with creating a Docker Extension, see the [Quickstart guide](quickstart.md). -Alternatively, get started with Part one: Build for more in-depth information about each step of the extension creation process. +Alternatively, get started with reading the "Part one: Build" section for more in-depth information about each step of the extension creation process. -For an in-depth tutorial of the entire build process, we recommend the following video walkthrough from DockerCon 2022: +For an in-depth tutorial of the entire build process, we recommend the following video walkthrough from DockerCon 2022. diff --git a/desktop/extensions-sdk/quickstart.md b/desktop/extensions-sdk/quickstart.md index 40d8173943..725b28f9a8 100644 --- a/desktop/extensions-sdk/quickstart.md +++ b/desktop/extensions-sdk/quickstart.md @@ -6,7 +6,7 @@ redirect_from: - desktop/extensions-sdk/tutorials/initialize/ --- -Follow the guide below to build a basic Docker Extension quickly. The Quickstart guide automatically generates boilerplate files for you. +Follow this guide to get started with building a basic Docker Extension. The Quickstart guide automatically generates boilerplate files for you. ## Prerequisites @@ -23,27 +23,27 @@ Follow the guide below to build a basic Docker Extension quickly. The Quickstart To set up your directory, use the `init` subcommand and provide a name for your extension. ```console -$ docker extension init my-extension +$ docker extension init ``` -You’ll be asked a series of questions about your extension, such as its name, a description, and the name of your Hub repository. This helps the CLI generate a set of boilerplate files for you to get started. The boilerplate files are stored in the directory `my-extension`. +The command asks a series of questions about your extension, such as its name, a description, and the name of your Hub repository. This helps the CLI generate a set of boilerplate files for you to get started. It stores the boilerplate files in the `my-extension` directory. The automatically generated extension contains: -- A backend service that listens on a socket. It has one endpoint `/hello` that returns a JSON payload. -- A React frontend that can call the backend and output the backend’s response. +- A Go backend service in the `backend` folder that listens on a socket. It has one endpoint `/hello` that returns a JSON payload. +- A React frontend in the `frontend` folder that can call the backend and output the backend’s response. For more information and guidelines on building the UI, see the [Design and UI styling section](design/design-guidelines.md). ## Step two: Build the extension -To build your extension, run: +To build the extension, move into the newly created directory and run: ```console $ docker build -t . ``` -`docker build` builds your extension and also generates an image which is named after your chosen hub repository. For instance, if you typed `john/my-extension` as the answer to the following question: +`docker build` builds the extension and generates an image named the same as the chosen hub repository. For example, if you typed `john/my-extension` as the answer to the following question: ```console ? Hub repository (eg. namespace/repository on hub): john/my-extension` @@ -59,7 +59,8 @@ To install the extension in Docker Desktop, run: $ docker extension install ``` -To preview the extension in Docker Desktop, open Docker Dashboard once the installation is complete. +To preview the extension in Docker Desktop, once the installation is complete and you should +see a **Quickstart** item underneath the **Extensions** menu. Selecting this item opens the extension's frontend. 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