diff --git a/docs/dev/cli/usage.md b/docs/dev/cli/usage.md index d1ed1db0..0477ef46 100644 --- a/docs/dev/cli/usage.md +++ b/docs/dev/cli/usage.md @@ -4,6 +4,7 @@ The Extensions CLI is an extension development tool that can be used to manage D - `docker extension enable` - enable Docker extensions - `docker extension disable` - disable Docker extensions +- `docker extension init` - create a new Docker extension - `docker extension install ` - install a Docker Extension with the specified image - `docker extension ls` - list installed Docker extensions - `docker extension rm` - remove a Docker extension diff --git a/docs/tutorials/images/initialized-extension.png b/docs/tutorials/images/initialized-extension.png new file mode 100644 index 00000000..8a1cc8fd Binary files /dev/null and b/docs/tutorials/images/initialized-extension.png differ diff --git a/docs/tutorials/initialize.md b/docs/tutorials/initialize.md new file mode 100644 index 00000000..834befa9 --- /dev/null +++ b/docs/tutorials/initialize.md @@ -0,0 +1,139 @@ +In this tutorial you will learn how to create a new Docker Desktop extension + +## Prerequisites + +- [Docker Desktop build with Extensions capabilities](https://github.com/docker/desktop-extension-samples/releases/) +- [Docker Extensions CLI](https://github.com/docker/desktop-extension-samples/releases/) +- [node](https://nodejs.org) + +## Creating a new extension + +To create a new extension run + +```bash +docker extension init my-extension +``` + +and answer the questions. + +This will create a directory `my-extension` with a bare-bones extension code. + +This extension contains: + +- A backend 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 response + +## Build the extension + +```bash +cd my-extension +make extension +``` + +## Install the extension + +Now that the extension is packaged as a Docker image, let's proceed with the +installation. To do so, we'll use the Docker Extensions CLI. + +!!! info "Enable Docker Desktop Extensions" + + Ensure the Extensions capabilities are enabled in the Docker Desktop build + by running `docker extension enable` + +To install the extension in Docker Desktop, run: + +```bash +docker extension install my-extension +``` + +If the installation was successful, you should see the following output: + +```bash +Installing new extension "my-extension" +Installing service in Desktop VM... +Setting additional compose attributes +VM service started +Installing Desktop extension UI for tab "My-Extension"... +Extension UI tab "My-Extension" added. +Extension "my-extension" installed successfully +``` + +## Preview the extension + +You can verify that the extension has been installed successfully using the +following CLI command: + +```bash +docker extension ls +``` + +It outputs all the extensions installed: + +```bash +ID PROVIDER VERSION UI VM HOST +my-extension Docker Inc. 1 tab(My-Extension) Running(1) - +``` + +On the left-menu, you should see a new tab with the name `My-Extension`. Click +on it to load the main window that will render a button. When you click on it +you should see the response from the backend + +![UI Extension](images/initialized-extension.png) + +### Opening Dev Tools + +To open the Chrome Developer Tools, see [this](../../dev/overview). + +### Iterate faster while developing + +To iterate faster and try out new changes when developing the extension, use the `docker extension update` command to uninstall the previous version and install the new one with your latest changes. + +### Developing the frontend + +If you are working on the frontend code of your extension and don't want to +rebuild the extension image each time you can setup Docker Desktop in a way +that will use your development server instead of the bundled frontend code from +the extension image. To do that, in one terminal start your UI development +server: + +```bash +cd ui +npm start +``` + +This will start a development server that listens on port 3000. You can now tell +Docker Desktop to use this as the frontend source, in another terminal run: + +```bash +docker extension dev ui-source my-extension http://localhost:3000 +``` + +Close and reoped the Docker Desktop dashboard and go to your extension, all the +changes to the frontend code will now be immediately visible. + +Once you are done you can remove the ui-source override by running + +```bash +docker extension dev reset my-extension +``` + + +## Clean up + +To remove the extension run: + +```bash +docker extension rm my-extension +``` + +The following output should be displayed: + +```bash +Removing extension my-extension... +Removing extension VM service... +Extension removed from Desktop VM +VM service socket forwarding stopped +Extension UI tab My-Extension removed +Extension "my-extension" removed +``` diff --git a/mkdocs.yml b/mkdocs.yml index c2a43fa7..5105ed17 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,6 +39,7 @@ markdown_extensions: nav: - Introduction: index.md - Tutorials: + - Create your first extension: tutorials/initialize.md - Create a minimal frontend extension: tutorials/minimal-frontend-extension.md - Create a minimal backend extension: tutorials/minimal-backend-extension.md - Create a ReactJS-based extension: tutorials/react-extension.md