centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-04-05 10:48:55 +07:00
Code Issues Packages Projects Releases Wiki Activity

extensions-sdk reorg

Browse Source 
- extensions-sdk reorg
- removal of tocs from API reference pages

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Allie Sadler
2022-06-10 14:40:37 +01:00
committed by Sebastiaan van Stijn
parent 60228db2fa
commit 4bcb3b2dc3
31 changed files with 560 additions and 980 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
_data/toc.yaml
View File

@@ -1237,67 +1237,69 @@ manuals:
- sectiontitle: Extensions SDK (Beta)
section:
- path: /desktop/extensions-sdk/
title: Introduction
- sectiontitle: Tutorials
title: Overview
- path: /desktop/extensions-sdk/quickstart/
title: Quickstart
- sectiontitle: "Part one: Build"
section:
- title: Create your first extension
path: /desktop/extensions-sdk/tutorials/initialize/
- title: Create a minimal frontend extension
path: /desktop/extensions-sdk/tutorials/minimal-frontend-extension/
- title: Create a ReactJS-based extension
path: /desktop/extensions-sdk/tutorials/react-extension/
- title: Create a minimal extension invoking docker commands
path: /desktop/extensions-sdk/tutorials/minimal-frontend-using-docker-cli/
- title: Create a minimal backend extension
path: /desktop/extensions-sdk/tutorials/minimal-backend-extension/
- sectiontitle: Design
- title: "Step one: Get started"
path: /desktop/extensions-sdk/build/get-started/
- sectiontitle: "Step two: Set up..."
section:
- title: ...a minimal frontend extension
path: /desktop/extensions-sdk/build/set-up/minimal-frontend-extension/
- title: ... a ReactJS-based extension
path: /desktop/extensions-sdk/build/set-up/react-extension/
- title: ... a minimal extension invoking Docker commands
path: /desktop/extensions-sdk/build/set-up/minimal-frontend-using-docker-cli/
- title: ... a minimal backend extension
path: /desktop/extensions-sdk/build/set-up/minimal-backend-extension/
- title: "Step three: Build and install"
path: /desktop/extensions-sdk/build/build-install/
- title: "Step four: Test and debug"
path: /desktop/extensions-sdk/build/test-debug/
- sectiontitle: "Part two: Publish"
section:
- title: Overview
path: /desktop/extensions-sdk/extensions/
- title: Metadata
path: /desktop/extensions-sdk/extensions/METADATA/
- title: Labels
path: /desktop/extensions-sdk/extensions/labels/
- title: Distribution
path: /desktop/extensions-sdk/extensions/DISTRIBUTION/
- title: Build multi-arch extensions
path: /desktop/extensions-sdk/extensions/multi-arch/
- sectiontitle: "Design and UI styling"
section:
- title: Guidelines
path: /desktop/extensions-sdk/design/design-guidelines/
- title: Docker's design principles
- title: Docker design principles
path: /desktop/extensions-sdk/design/design-principles/
- sectiontitle: UI Styling
section:
- title: Overview
- title: UI styling guidelines
path: /desktop/extensions-sdk/design/overview/
- title: MUI best practices
path: /desktop/extensions-sdk/design/mui-best-practices/
- sectiontitle: Developer SDK tools
section:
- title: Overview
path: /desktop/extensions-sdk/dev/overview/
- title: CLI overview
path: /desktop/extensions-sdk/dev/cli/usage/
- title: Build, test and install an extension
path: /desktop/extensions-sdk/dev/cli/build-test-install-extension/
- title: OAuth 2.0 flow
- title: Authentication
path: /desktop/extensions-sdk/dev/oauth2-flow/
- sectiontitle: Publishing extensions
section:
- title: Metadata
path: /desktop/extensions-sdk/extensions/METADATA/
- title: Labels
path: /desktop/extensions-sdk/extensions/labels/
- title: Validation
path: /desktop/extensions-sdk/extensions/validation/
- title: Distribution
path: /desktop/extensions-sdk/extensions/DISTRIBUTION/
- title: Building multi-arch extensions
path: /desktop/extensions-sdk/extensions/multi-arch/
- sectiontitle: Extension APIs
section:
- title: Overview
path: /desktop/extensions-sdk/dev/api/overview/
- title: Extension Backend
path: /desktop/extensions-sdk/dev/api/backend/
- title: Docker
path: /desktop/extensions-sdk/dev/api/docker/
- title: Dashboard
path: /desktop/extensions-sdk/dev/api/dashboard/
- title: Navigation
path: /desktop/extensions-sdk/dev/api/dashboard-routes-navigation/
- title: API Reference
path: /desktop/extensions-sdk/dev/api/reference/README/
- title: CLI reference
path: /desktop/extensions-sdk/dev/usage/
- sectiontitle: Extension APIs
section:
- title: Overview
path: /desktop/extensions-sdk/dev/api/overview/
- title: Extension Backend
path: /desktop/extensions-sdk/dev/api/backend/
- title: Docker
path: /desktop/extensions-sdk/dev/api/docker/
- title: Dashboard
path: /desktop/extensions-sdk/dev/api/dashboard/
- title: Navigation
path: /desktop/extensions-sdk/dev/api/dashboard-routes-navigation/
- title: API Reference
path: /desktop/extensions-sdk/dev/api/reference/README/
- path: /desktop/multi-arch/
title: Multi-arch support
- path: /desktop/kubernetes/

65
desktop/extensions-sdk/build/build-install.md
View File

@@ -1,54 +1,59 @@
---
title: Build, test, and install an extension
description: Docker extension CLI
keywords: Docker, extensions, sdk, cli
title: "Step three: Build and install"
description: Step three in the extension creation process
keywords: Docker, Extensions, sdk, validate, install
redirect_from:
- /desktop/extensions-sdk/extensions/validation/
- /desktop/extensions-sdk/dev/cli/build-test-install-extension/
---
The [sample folder](https://github.com/docker/extensions-sdk/tree/main/samples) contains multiple extensions.
These are Docker developed samples that are not meant to be final products.
Once you have set up your directory correctly, you can build your extension for single or multiple architectures.
To use one of them, navigate to the directory of the extension then build and install it on Docker Desktop.
The `docker extension` commands are carried out by the Extension CLI which is a developer tool. It is not included in the standard Docker Desktop package.
## Build the extension for a single architecture
To build the extension, run:
```console
$ make build-extension
# or docker build -t my-extension .
```
`docker build -t <name-of-your-extension> .`
To install the extension, run:
## Validate your extension
```console
$ docker extension install my-extension
```
The Extensions CLI lets you validate your extension before installing and running it locally.
> Using the CLI to install unpublished extensions
>
The validation checks if the extension’s `Dockerfile` specifies all the required labels and if the metadata file is valid against the JSON schema file.
To validate, run:
`docker extension validate <name-of-your-extension>`
If your extension is valid, the message below displays:
`The extension image "name-of-your-extension" is valid`.
Before the image is built, it is also possible to validate only the metadata.json file:
`$ 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).
## Install the extension
To install the extension in Docker Desktop, run:
`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.
> {: .warning}
To list all your installed extensions, run:
```console
```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)
tailscale/docker-extension Tailscale Inc. 0.0.2 1 tab(Tailscale) Running(1) 1 binarie(s)
```
To remove the extension, run:
## What's next?
```console
$ docker extension rm my-extension
```
To update an extension with a newer version (local or remote image), run:
```console
$ docker extension update docker/hub-explorer-extension:0.0.3
```
Learn how to [test and debug](test-debug.md) your extension.

188
desktop/extensions-sdk/build/get-started.md
View File

@@ -1,154 +1,98 @@
---
title: Extensions SDK tutorials
description: index for Docker Extensions SDK tutorials
keywords: Docker, Extensions, sdk, tutorial
title: "Step one: Get started"
description: The first step to building an extension.
keywords: Docker, Extensions, sdk, prerequisites
redirect_from:
- desktop/extensions-sdk/tutorials/initialize/
---
Learn how to create a new Docker 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.
## Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- [Docker Extensions CLI](https://github.com/docker/extensions-sdk/releases/)
- [NodeJS](https://nodejs.org)
- [Go](https://go.dev/dl/)
Before you create your own extension, you need to install [Docker Desktop](../../release-notes.md).
> Note
You also need the latest [Extensions CLI](https://github.com/docker/extensions-sdk/releases/latest), which is used to manage extensions later on.
> Using the CLI to install unpublished extensions
>
> NodeJS and Go are only required if an extension is created using the `docker extension init` command. This command uses a template based on a ReactJS and Go application.
> Extensions can install binaries, invoke commands and access files on your machine. Make sure you trust extensions before installing them on your machine.
> {: .warning}
## Create a new extension
Once you've downloaded the Extensions CLI, extract the binary in to `~/.docker/cli-plugins`.
To create a new extension, use the `init` subcommand and provide a name for your extension.
In your terminal, run:
```bash
docker extension init my-extension
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#prereq-macos-intel">MacOS (intel)</a></li>
<li><a data-toggle="tab" data-target="#prereq-macos-m1">MacOS (M1)</a></li>
<li><a data-toggle="tab" data-target="#prereq-windows">Windows</a></li>
<li><a data-toggle="tab" data-target="#prereq-wsl2">WSL2</a></li>
<li><a data-toggle="tab" data-target="#prereq-linux">Linux</a></li>
</ul>
<div class="tab-content">
<div id="prereq-macos-intel" class="tab-pane fade in active" markdown="1">
```console
$ tar -xvzf desktop-extension-cli-darwin-amd64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
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 to generate a set of boilerplate files for you to get started. The boilerplate files are stored in the directory `my-extension`.
<hr></div>
<div id="prereq-macos-m1" class="tab-pane fade" markdown="1">
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.
## Build the extension
As part of the extension boilerplate files, a `Makefile` is generated at the root of the extension directory with targets to build and push the extension.
To build the extension, run:
```bash
cd my-extension
make build-extension
```console
$ tar -xvzf desktop-extension-cli-darwin-arm64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
`make build-extension` 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:
<hr></div>
<div id="prereq-windows" class="tab-pane fade" markdown="1">
```
? Hub repository (eg. namespace/repository on hub): john/my-extension
```console
PS> tar -xvzf desktop-extension-cli-windows-amd64.tar.gz
PS> mkdir -p ~/.docker/cli-plugins
PS> mv docker-extension.exe ~/.docker/cli-plugins
```
The `make build-extension` generates an image with name `john/my-extension`.
<hr></div>
<div id="prereq-wsl2" class="tab-pane fade" markdown="1">
## Install the extension
To install the extension in Docker Desktop, run:
```bash
docker extension install john/my-extension
```console
$ tar -xvzf desktop-extension-cli-linux-amd64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
If the installation is successful, the following output displays:
<hr></div>
<div id="prereq-linux" class="tab-pane fade" markdown="1">
```bash
Installing new extension "john/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
```console
$ tar -xvzf desktop-extension-cli-linux-amd64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
## Preview the extension
<hr></div>
</div>
You can also enter the command below to verify the extension installed successfully:
You can now list installed extensions (the list should be empty if you have not installed extensions already):
```bash
docker extension ls
```console
$ docker extension ls
ID PROVIDER VERSION UI VM HOST
```
It outputs all the extensions installed:
![Extensions enabled](images/extensions-enabled.png)
```bash
ID PROVIDER VERSION UI VM HOST
john/my-extension Docker Inc. 1 tab(My-Extension) Running(1) -
```
You can now continue to step two and set up your directory.
In Docker Desktop, the left-hand menu now displays a new tab with the name `My-Extension`. When you select the new tab, a **Call Backend** button appears. When you select it, it displays a response from the backend.
## What’s next?
![UI Extension](images/initialized-extension.png)
### Opening Dev Tools
You can now develop your custom Docker Extension. See the [Developer guide](../../dev/overview) for more information.
### Iterate faster while developing
To iterate faster and try out new changes whilst you develop your extension, use the `docker extension update` command. This uninstalls the previous version and installs the new one with your latest changes.
### Developing the frontend
During UI development, it's helpful to use hot reloading to test your changes without rebuilding your entire extension.
To do this, you can configure Docker Desktop to load your UI from a development server, such as the one Create React
App starts when invoked with yarn start.
Assuming your app runs on the default port, start your UI app and then run:
```bash
cd ui
npm start
```
This starts 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 john/my-extension http://localhost:3000
```
Close and reopen the Docker Desktop dashboard and go to your extension. All the
changes to the frontend code are immediately visible.
Once you're done you can remove the ui-source override:
```bash
docker extension dev reset john/my-extension
```
## Submit your extension to the marketplace
If you want to make your extension available to all Docker Desktop users, you can submit it for publication in the Marketplace. For more information, see [Publish your extension in the Marketplace](../extensions/DISTRIBUTION.md#publish-your-extension-in-the-marketplace).
## Clean up
To remove the extension, run:
```bash
docker extension rm john/my-extension
```
The following output displays:
```bash
Removing extension john/my-extension...
Removing extension VM service...
Extension removed from Desktop VM
VM service socket forwarding stopped
Extension UI tab My-Extension removed
Extension "john/my-extension" removed
```
Explore how to set up:
- [A frontend extension based on plain HTML](set-up/minimal-frontend-extension.md)
- [A simple Docker extension that contains only a UI part and is based on ReactJS](set-up/react-extension.md)
- [An extension that invokes Docker CLI commands](set-up/minimal-frontend-using-docker-cli.md)
- [A simple backend extension](set-up/minimal-backend-extension.md)

0
desktop/extensions-sdk/images/extensions-enabled.png → desktop/extensions-sdk/build/images/extensions-enabled.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 603 KiB

After

Width:  |  Height:  |  Size: 603 KiB

0
desktop/extensions-sdk/tutorials/images/ui-minimal-extension.png → desktop/extensions-sdk/build/images/ui-minimal-extension.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 541 KiB

After

Width:  |  Height:  |  Size: 541 KiB

0
desktop/extensions-sdk/tutorials/images/backend-minimal-extension.png → desktop/extensions-sdk/build/set-up/images/backend-minimal-extension.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 526 KiB

After

Width:  |  Height:  |  Size: 526 KiB

0
desktop/extensions-sdk/tutorials/images/docker-cli-minimal-extension.png → desktop/extensions-sdk/build/set-up/images/docker-cli-minimal-extension.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 542 KiB

After

Width:  |  Height:  |  Size: 542 KiB

0
desktop/extensions-sdk/tutorials/images/initialized-extension.png → desktop/extensions-sdk/build/set-up/images/initialized-extension.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 555 KiB

After

Width:  |  Height:  |  Size: 555 KiB

0
desktop/extensions-sdk/tutorials/images/types-autocomplete.png → desktop/extensions-sdk/build/set-up/images/types-autocomplete.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

0
desktop/extensions-sdk/tutorials/images/ui-extension-hello-world.png → desktop/extensions-sdk/build/set-up/images/ui-extension-hello-world.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 165 KiB

After

Width:  |  Height:  |  Size: 165 KiB

0
desktop/extensions-sdk/tutorials/images/ui-extension-react.png → desktop/extensions-sdk/build/set-up/images/ui-extension-react.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 512 KiB

After

Width:  |  Height:  |  Size: 512 KiB

0
desktop/extensions-sdk/tutorials/images/ui-minimal-extension-dark.png → desktop/extensions-sdk/build/set-up/images/ui-minimal-extension-dark.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 566 KiB

After

Width:  |  Height:  |  Size: 566 KiB

138
desktop/extensions-sdk/build/set-up/minimal-backend-extension.md
View File

@@ -1,24 +1,18 @@
---
title: Minimal backend extension tutorial
title: Set up a minimal backend extension
description: Minimal backend extension tutorial
keywords: Docker, extensions, sdk, tutorial
keywords: Docker, extensions, sdk, build
redirect_from:
- /desktop/extensions-sdk/tutorials/minimal-backend-extension/
---
Learn how to create a simple Docker Extension that runs CLI commands in the backend.
Set up a simple Docker Extension that runs CLI commands in the backend.
For extensions with a backend service running REST services over sockets or named pipes, see the `vm-ui extension` [sample](https://github.com/docker/extensions-sdk/tree/main/samples).
## Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- [Docker Extensions CLI](https://github.com/docker/extensions-sdk/releases/)
## Extension folder structure
A Docker extension is made of several files which range from the extension's source code to the required extension-specific files.
In the `minimal-backend` [sample folder](https://github.com/docker/extensions-sdk/tree/main/samples), you can find a ready-to-go example that represents a UI extension built on HTML that runs a backend service. We will go through this code example in this tutorial.
Although you can start from an empty directory, it is highly recommended that you start from the template below and change it accordingly to suit your needs.
@@ -33,16 +27,21 @@ Although you can start from an empty directory, it is highly recommended that yo
│ └── ... React aplication
├── hello.sh # (3)
└── metadata.json # (4)
└── ui # (5)
└── index.html
```
1. Contains everything required to build the extension and run it in Docker Desktop.
2. The source folder that contains the UI application. In this example we use a React frontend, the main part of th extension is an App.tsx.
3. The script that runs inside the container.
4. A file that provides information about the extension such as the name, description, and version.
5. 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).
If you want to set up user authentication for the extension, see [Authentication](../../dev/oauth2-flow.md).
## Invoke the extension backend from your javascript code
Let's reuse the React extension from the [React extension tutorial](./react-extension.md), and see how we can invoke our extension backend from the App.tsx file.
Using the [React extension example](./react-extension.md), we can invoke our extension backend from the App.tsx file.
Use the Docker Desktop Client object and then invoke a binary provided in our backend container (that lives inside the Docker Desktop VM) with `ddClient.docker.extension.vm.cli.exec()`.
In our example, our hello.sh script returns a string as result, we obtain it with `result?.stdout`.
@@ -61,8 +60,6 @@ async function runExtensionBackend(inputText: string) {
## Create a Dockerfile
An extension requires a `Dockerfile` to build, publish, and run the extension in Docker Desktop.
At minimum, your Dockerfile needs:
- Labels which provide extra information about the extension.
@@ -107,121 +104,16 @@ A `metadata.json` file is required at the root of the image filesystem.
}
```
> Do not replace the `${DESKTOP_PLUGIN_IMAGE}` placeholder in the `metadata.json` file. The placeholder is replaced automatically with the correct image name when the extension is installed.
For more information on the `metadata.json`, see [Metadata](../../extensions/METADATA.md).
## Build the extension
To build the extension, run:
```bash
docker build -t desktop-backend-minimal-extension:0.0.1 .
```
### Build the extension for multiple platforms
To build the extension for multiple platforms, run:
```bash
docker buildx build --platform=linux/amd64,linux/arm64 -t desktop-backend-minimal-extension:0.0.1 .
```
## Validate the extension
Verify the extension image is compliant.
The validation checks if the extension's `Dockerfile` specifies all the required labels and if the metadata file is valid against the JSON schema file.
```bash
docker extension validate desktop-backend-minimal-extension:0.0.1
```
If your extension is valid, the message below displays:
`The extension image "desktop-backend-minimal-extension:0.0.1" is valid`.
## Install the extension
To install the extension in Docker Desktop, run:
```bash
docker extension install desktop-backend-minimal-extension:0.0.1
```
If the installation is successful, the output below displays:
```bash
Installing new extension "hello-backend" with desktop-backend-minimal-extension:0.0.1 ...
Installing service in Desktop VM...
Setting additional compose attributes
VM service started
Installing Desktop extension UI for tab "Hello Backend Extension"...
Extension UI tab "Hello Backend Extension" added.
Extension "hello-backend" installed successfully
```
## Preview the extension
You can also enter the command below to verify the extension installed successfully:
```bash
docker extension ls
```
It outputs all the extensions installed:
```bash
PLUGIN PROVIDER IMAGE UI VM HOST
hello-backend Docker Inc. desktop-backend-minimal-extension:0.0.1 1 tab(Hello Backend Extension) Running(1) -
```
To preview the extension in Docker Desktop, close and open the Docker Desktop dashboard once the installation has completed.
The left-hand menu displays a new tab with name `Hello Backend Extension`. When you select the new tab, the result below is rendered.
![Backend Hello Extension](images/backend-minimal-extension.png)
## Publish the extension
To publish the extension, upload the Docker image to [DockerHub](https://hub.docker.com).
Tag the previous image to prepend the account owner at the beginning of the image name:
```bash
docker tag desktop-backend-minimal-extension:0.0.1 owner/desktop-backend-minimal-extension:0.0.1
```
Push the image to DockerHub:
```bash
docker push owner/desktop-backend-minimal-extension:0.0.1
```
> Publishing extensions in the marketplace
> **Warning**
>
> For Docker Extensions images to be listed in Docker Desktop, they must be approved by Docker and be tagged following semantic versioning, e.g: `0.0.1`.
>
> See [distribution and new releases](../extensions/DISTRIBUTION.md#distribution-and-new-releases) for more information.
>
> See <a href="https://semver.org/" target="__blank">semver.org</a> to learn more about semantic versioning.
>Do not replace the `${DESKTOP_PLUGIN_IMAGE}` placeholder in the `metadata.json` file. The placeholder is replaced automatically with the correct image name when the extension is installed.
{: .warning}
> Having trouble to push the image?
>
> Ensure you are logged into DockerHub. Otherwise, run `docker login` to authenticate.
## Clean up
## What's next?
To remove the extension, run:
Learn how to [build and install your extension](../build-install.md).
```bash
docker extension rm hello-backend
```
The following output displays:
```bash
Removing extension hello-backend...
Removing extension VM service...
Extension removed from Desktop VM
Extension UI tab Hello Backend Extension removed
Extension "hello-backend" removed
```

187
desktop/extensions-sdk/build/set-up/minimal-frontend-extension.md
View File

@@ -1,22 +1,15 @@
---
title: Minimal frontend extension tutorial
title: Set up a minimal frontend extension
description: Minimal frontend extension tutorial
keywords: Docker, extensions, sdk, tutorial
keywords: Docker, extensions, sdk, build
redirect_from:
- /desktop/extensions-sdk/tutorials/minimal-frontend-extension/
---
Learn how to create a minimal frontend extension based on plain HTML.
## Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- [Docker Extensions CLI](https://github.com/docker/extensions-sdk/releases/)
Set up a minimal frontend extension based on plain HTML.
## Extension folder structure
A Docker extension is made of several files which range from the extension's source code to the required extension-specific files.
In the `minimal-frontend` [sample folder](https://github.com/docker/extensions-sdk/tree/main/samples), you can find a ready-to-go example that represents a UI Extension built on HTML. We will go through this code example in this tutorial.
Although you can start from an empty directory, it is highly recommended that you start from the template below and change it accordingly to suit your needs.
@@ -31,12 +24,12 @@ 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.
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).
If you want to set up user authentication for the extension, see [Authentication](../../dev/oauth2-flow.md).
## Create a Dockerfile
An extension requires a `Dockerfile` to build, publish, and run in Docker Desktop.
At a minimum, your Dockerfile needs:
- Labels which provide extra information about the extension.
@@ -72,172 +65,8 @@ A `metadata.json` file is required at the root of the image filesystem.
}
```
## Build the extension
To build the extension, run:
```bash
docker build -t desktop-frontend-minimal-extension:0.0.1 .
```
### Build the extension for multiple platforms
To build the extension for multiple platforms, run:
```bash
docker buildx build --platform=linux/amd64,linux/arm64 -t desktop-frontend-minimal-extension:0.0.1 .
```
## Validate the extension
Verify the extension image is compliant.
The validation checks if the extension's `Dockerfile` specifies all the required labels and if the metadata file is valid against the JSON schema file.
```bash
docker extension validate desktop-frontend-minimal-extension:0.0.1
```
If your extension is valid, the message below displays:
`The extension image "desktop-frontend-minimal-extension:0.0.1" is valid`.
## Install the extension
To install the extension in Docker Desktop, run:
```bash
docker extension install desktop-frontend-minimal-extension:0.0.1
```
If the installation is successful, the output below displays:
```bash
Installing new extension "MinimalFrontEnd" with desktop-frontend-minimal-extension:0.0.1 ...
Installing Desktop extension UI for tab "Min FrontEnd Extension"...
Extension UI tab "Min FrontEnd Extension" added.
Extension "MinimalFrontEnd" installed successfully
```
## Preview the extension
You can also enter the command below to verify the extension installed successfully:
```bash
docker extension ls
```
It outputs all the extensions installed:
```bash
PLUGIN PROVIDER IMAGE UI VM HOST
MyExtension Docker Inc. desktop-frontend-minimal-extension:0.0.1 1 tab(Min FrontEnd Extension) - -
```
To preview the extension in Docker Desktop, close and open the Docker Desktop dashboard once the installation is complete.
The left-hand menu displays a new tab with the name `Min FrontEnd Extension`. When you select the new tab, `Hello, World!` displays in the top-left corner.
![UI Extension](images/ui-minimal-extension.png)
## Update the extension
To update the extension, you must first rebuild and revalidate your extension. You can then use the update command.
As an example, let's update the html file to include some inline CSS to support a dark mode.
```html
<head>
<style>
@media (prefers-color-scheme: dark) {
body {
background-color: #333;
}
h1 {
color: white;
}
}
</style>
...
</head>
```
Alternatively remove the `index.html` file and rename `updatedindex.html` to index.html in the ui directory.
Rebuild and revalidate the extension:
```bash
docker build -t desktop-frontend-minimal-extension:0.0.1 .
docker extension validate desktop-frontend-minimal-extension:0.0.1
```
Now update the extension:
```bash
docker extension update desktop-frontend-minimal-extension:0.0.1
```
If the update is successful, the following output displays:
```bash
Removing extension desktop-frontend-minimal-extension:0.0.1...
Extension UI tab Min FrontEnd Extension removed
Extension "MinimalFrontEnd" removed
Installing new extension "desktop-frontend-minimal-extension:0.0.1"
Installing Desktop extension UI for tab "Min FrontEnd Extension"...
Extension UI tab "Min FrontEnd Extension" added.
Extension "MinimalFrontEnd" installed successfully
```
When you run Docker Desktop in dark mode and click the `Min FrontEnd Extension` tab, it renders with dark mode colors.
![UI Extension](images/ui-minimal-extension-dark.png)
## Publish the extension
To publish the extension, upload the Docker image to [DockerHub](https://hub.docker.com).
Tag the previous image to prepend the account owner at the beginning of the image name:
```bash
docker tag desktop-frontend-minimal-extension:0.0.1 owner/desktop-frontend-minimal-extension:0.0.1
```
Push the image to DockerHub:
```bash
docker push owner/desktop-frontend-minimal-extension:0.0.1
```
> Publishing extensions in the marketplace
>
> For Docker Extensions images to be listed in Docker Desktop, they must be approved by Docker and the tags must follow semantic versioning, e.g: `0.0.1`.
>
> See [distribution and new releases](../extensions/DISTRIBUTION.md#distribution-and-new-releases) for more information.
>
> See <a href="https://semver.org/" target="__blank">semver.org</a> to learn more about semantic versioning.
> Having trouble to push the image?
>
> Ensure you are logged into DockerHub. Otherwise, run `docker login` to authenticate.
## Clean up
To remove the extension, run:
```bash
docker extension rm desktop-frontend-minimal-extension
```
The following output displays:
```bash
Removing extension desktop-frontend-minimal-extension...
Extension UI tab Min FrontEnd Extension removed
Extension "MinimalFrontEnd" removed
```
For more information on the `metadata.json`, see [Metadata](../../extensions/METADATA.md).
## What's next?
Learn how to [create an extension using React.](./react-extension.md)
Learn how to [build and install your extension](../build-install.md).

135
desktop/extensions-sdk/build/set-up/minimal-frontend-using-docker-cli.md
View File

@@ -1,22 +1,15 @@
---
title: Minimal docker CLI extension tutorial
title: Set up a minimal extension invoking Docker commands
description: Minimal docker CLI extension tutorial
keywords: Docker, extensions, sdk, tutorial
keywords: Docker, extensions, sdk, build
redirect_from:
- /desktop/extensions-sdk/tutorials/minimal-frontend-using-docker-cli/
---
Learn how to create a simple Docker extension that invokes Docker CLI commands.
## Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- [Docker Extensions CLI](https://github.com/docker/extensions-sdk/releases/)
Set up a simple Docker extension that invokes Docker CLI commands.
## Extension folder structure
A Docker extension is made of several files which range from the extension's source code to the required extension-specific files.
In the `minimal-docker-cli` [sample folder](https://github.com/docker/extensions-sdk/tree/main/samples), you can find a ready-to-go example that represents a UI Extension invoking Docker commands. We will go through this code example in this tutorial.
Although you can start from an empty directory, it is highly recommended that you start from the template below and change it accordingly to suit your needs.
@@ -33,11 +26,13 @@ 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. In this example we use a React frontend, the main part of th extension is an App.tsx.
3. The source folder that contains all your HTML, CSS and JS files. In this example we use a React frontend, the main part of th extension is an App.tsx. 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](../../dev/oauth2-flow.md).
## Invoke docker CLI in your javascript code
Let's reuse the React extension from the [React extension tutorial](./react-extension.md), and see how we can invoke docker commands from the App.tsx file.
Using the [React extension example](./react-extension.md), we can invoke docker commands from the App.tsx file.
Use the Docker Desktop Client object to discover extension APIs about `docker`. The application uses `@docker/extension-api-client` in order to obtain a Docker Desktop Client object. Because we have set `@docker/extension-api-client-types` as a dev dependency, we also have auto-completion in our IDE:
@@ -67,8 +62,6 @@ We can then use our `dockerInfo` object in the display part of the application.
## Create a Dockerfile
An extension requires a `Dockerfile` to build, publish, and run in Docker Desktop.
At minimum, your Dockerfile needs:
- Labels which provide extra information about the extension.
@@ -107,118 +100,8 @@ A `metadata.json` file is required at the root of the image filesystem.
}
```
## Build the extension
To build the extension, run:
```bash
docker build -t desktop-docker-cli-minimal-extension:0.0.1 .
```
### Build the extension for multiple platforms
To build the extension for multiple platforms, run:
```bash
docker buildx build --platform=linux/amd64,linux/arm64 -t desktop-docker-cli-minimal-extension:0.0.1 .
```
## Validate the extension
Verify the extension image is compliant.
The validation checks if the extension's `Dockerfile` specifies all the required labels and if the metadata file is valid against the JSON schema file.
```bash
docker extension validate desktop-docker-cli-minimal-extension:0.0.1
```
If your extension is valid, the message below displays:
`The extension image "desktop-docker-cli-minimal-extension:0.0.1" is valid`.
## Install the extension
To install the extension in Docker Desktop, run:
```bash
docker extension install desktop-docker-cli-minimal-extension:0.0.1
```
If the installation is successful, the output below displays:
```bash
Installing new extension "MyExtension" with desktop-docker-cli-minimal-extension:0.0.1 ...
Installing Desktop extension UI for tab "My Extension"...
Extension UI tab "Docker VM info" added.
Extension "MyExtension" installed successfully
```
## Preview the extension
You can also enter the command below to verify the extension installed successfully:
```bash
docker extension ls
```
It outputs all the extensions installed:
```bash
PLUGIN PROVIDER IMAGE UI VM HOST
MyExtension Docker Inc. desktop-docker-cli-minimal-extension:0.0.1 1 tab(My Extension) - -
```
To preview the extension in Docker Desktop, close and open the Docker Desktop dashboard once the installation is complete.
The left-hand menu displays a new tab with name `Docker VM info`. When you select the new tab, the result below is rendered.
![UI Extension](images/docker-cli-minimal-extension.png)
## Publish the extension
To publish the extension, upload the Docker image to [DockerHub](https://hub.docker.com).
Tag the previous image to prepend the account owner at the beginning of the image name:
```bash
docker tag desktop-docker-cli-minimal-extension:0.0.1 owner/desktop-docker-cli-minimal-extension:0.0.1
```
Push the image to DockerHub:
```bash
docker push owner/desktop-docker-cli-minimal-extension:0.0.1
```
> Publishing extensions in the marketplace
>
> For Docker Extensions images to be listed in Docker Desktop, they must be approved by Docker and be tagged following semantic versioning, e.g: `0.0.1`.
>
> See [distribution and new releases](../extensions/DISTRIBUTION.md#distribution-and-new-releases) for more information.
>
> See <a href="https://semver.org/" target="__blank">semver.org</a> to learn more about semantic versioning.
> Having trouble to push the image?
>
> Ensure you are logged into DockerHub. Otherwise, run `docker login` to authenticate.
## Clean up
To remove the extension, run:
```bash
docker extension rm desktop-docker-cli-minimal-extension
```
The following output displays:
```bash
Removing extension MyExtension...
Extension UI tab Disk usage removed
Extension "MyExtension" removed
```
For more information on the `metadata.json`, see [Metadata](../../extensions/METADATA.md).
## What's next?
Learn how to [create a minimal backend extension.](./minimal-backend-extension.md)
Learn how to [build and install your extension](../build-install.md).

146
desktop/extensions-sdk/build/set-up/react-extension.md
View File

@@ -1,22 +1,15 @@
---
title: Minimal react extension tutorial
title: Set up a minimal react extension
description: Minimal react extension tutorial
keywords: Docker, extensions, sdk, tutorial
keywords: Docker, extensions, sdk, build
redirect_from:
- /desktop/extensions-sdk/tutorials/react-extension/
---
Learn how to create a simple Docker extension that contains only a UI part and is based on ReactJS.
## Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- [Docker Extensions CLI](https://github.com/docker/extensions-sdk/releases/)
Set up a simple Docker extension that contains only a UI part and is based on ReactJS.
## Extension folder structure
A Docker extension is made of several files which range from the extension's source code to the required extension-specific files.
In the `react-extension` [sample folder](https://github.com/docker/extensions-sdk/tree/main/samples), you can find a ready-to-go example that represents a UI Extension built on ReactJS. We will go through this code example in this tutorial.
Although you can start from an empty directory, it is highly recommended that you start from the template below and change it accordingly to suit your needs.
@@ -42,13 +35,17 @@ 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. High-level folder containing your front-end app source code.
3. Assets that aren’t compiled or dynamically generated are stored here. These can be static assets like logos or the robots.txt file.
4. The src, or source folder contains all the React components, external CSS files, and dynamic assets that are brough into the component files.
4. The src, or source folder contains all the React components, external CSS files, and dynamic assets that are brought into the component files.
5. The icon that is displayed in the left-menu of the Docker Desktop Dashboard.
6. A file that provides information about the extension such as the name, description, and version.
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](../../dev/oauth2-flow.md).
## Create a Dockerfile
An extension requires a `Dockerfile` to build, publish, and run in Docker Desktop.
Use the Dockerfile below as a template and change it accodingly to suit your needs.
```Dockerfile
FROM node:14.17-alpine3.13 AS client-builder
@@ -113,129 +110,8 @@ export function App() {
}
```
## Build the extension
To build the extension, run:
```bash
docker build -t desktop-react-extension:0.0.1 .
```
### Build the extension for multiple platforms
To build the extension for multiple platforms, run:
```bash
docker buildx build --platform=linux/amd64,linux/arm64 -t desktop-react-extension:0.0.1 .
```
## Validate the extension
Verify the extension image is compliant.
The validation checks if the extension's `Dockerfile` specifies all the required labels and if the metadata file is valid against the JSON schema file.
```bash
docker extension validate desktop-backend-minimal-extension:0.0.1
```
If your extension is valid, the message below displays:
`The extension image "desktop-backend-minimal-extension:0.0.1" is valid`.
## Install the extension
To install the extension in Docker Desktop, run:
```bash
docker extension install desktop-react-extension:0.0.1
```
If the installation is successful, the output below displays:
```bash
Installing new extension "ui-extension" with desktop-react-extension:0.0.1 ...
Installing Desktop extension UI for tab "UI Extension"...
Extension UI tab "UI Extension" added.
Extension "ui-extension" installed successfully
```
## Preview the extension
You can also enter the command below to verify the extension installed successfully:
```bash
docker extension ls
```
It outputs all the extensions installed:
```bash
PLUGIN PROVIDER IMAGE UI VM HOST
ui-extension #(1) Docker Inc. (2) desktop-react-extension:0.0.1 (3) 1 tab(UI Extension)(4) -(5) -(6)
```
1. Name of the extension (from property `name` in `metadata.json`).
2. Provider of the extension (from property `provider` in `metadata.json`)
3. Docker image name
4. Tab name (from property `ui.dashboard-tab.title` in `metadata.json`)
5. No backend services running in the Desktop VM.
6. No binaries deployed on the host.
To preview the extension in Docker Desktop, close and open the Docker Desktop dashboard once the installation is complete.
The left-hand menu displays a new tab with the name `UI Extension`. When you select the new tab, a button appears in the top-left corner. Click the button to display `Hello, World!`.
![UI Extension](images/ui-extension-react.png)
### Open Dev Tools
See the [Developer guide](../../dev/overview) for more information.
## Publish the extension
To publish the extension, upload the Docker image to [DockerHub](https://hub.docker.com).
Tag the previous image to prepend the account owner at the beginning of the image name:
```bash
docker tag desktop-react-extension:0.0.1 owner/desktop-react-extension:0.0.1
```
Push the image to DockerHub:
```bash
docker push owner/desktop-react-extension:0.0.1
```
> Publishing extensions in the marketplace
>
> For Docker Extensions images to be listed in Docker Desktop, they must be approved by Docker and be tagged following semantic versioning, e.g: `0.0.1`.
>
> See [distribution and new releases](../extensions/DISTRIBUTION.md#distribution-and-new-releases) for more information.
>
> See <a href="https://semver.org/" target="__blank">semver.org</a> to learn more about semantic versioning.
> Having trouble to push the image?
>
> Ensure you are logged into DockerHub. Otherwise, run `docker login` to authenticate.
## Clean up
To remove the extension, run:
```bash
docker extension rm ui-extension
```
The following output displays:
```bash
Removing extension ui-extension...
Extension UI tab UI Extension removed
Extension "ui-extension" removed
```
For more information on the `metadata.json`, see [Metadata](../../extensions/METADATA.md).
## What's next?
Learn how to [create an extension using Docker CLI commands.](./minimal-frontend-using-docker-cli.md)
Learn how to [build and install your extension](../build-install.md).

72
desktop/extensions-sdk/build/test-debug.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: "Step four: Test and debug"
description: Step four in the extension creation process
keywords: Docker, Extensions, sdk, preview, update, Chrome DevTools
---
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)
### Open Chome DevTools
In order to open the Chrome DevTools for your extension when you click on the extension tab, run:
`$ docker extension dev debug <name-of-your-extensions>`
Each subsequent click on the extension tab will also open Chrome Dev Tools. To stop this behaviour, run:
`$ docker extension dev reset <name-of-your-extensions>`
After an extension is deployed, it is also possible to open Chrome DevTools from the UI extension part using a variation of the [Konami Code](https://en.wikipedia.org/wiki/Konami_Code). Click on the extension tab, and then hit the key sequence `up, up, down, down, left, right, left, right, p, d, t`.
### Hot reloading whilst developing the UI
During UI development, it’s helpful to use hot reloading to test your changes without rebuilding your entire extension. To do this, you can configure Docker Desktop to load your UI from a development server, such as the one Create React App starts when invoked with yarn start.
Assuming your app runs on the default port, start your UI app and then run:
```
cd ui
npm start
```
This starts 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:
`$ docker extension dev ui-source <name-of-your-extensions> http://localhost:3000`
Close and reopen the Docker Desktop dashboard and go to your extension. All the changes to the frontend code are immediately visible.
Once finished, you can reset the extension configuration to the original settings. This will also reset opening Chrome dev tools if you used `docker extension dev debug <name-of-your-extensions>`:
`$ docker extension dev reset <name-of-your-extensions>`
## Show the extension containers
If your extension is composed of one or more services running as containers in the Docker Desktop VM, you can access them easily from the dashboard in Docker Desktop.
1. In Docker Desktop, navigate to **Settings** or **Preferences** if you’re a Mac user.
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.
`docker extension update <name-of-your-extensions>`
## 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](../dev/oauth2-flow.md)
- Learn how to [publish your extension](../extensions/index.md).

32
desktop/extensions-sdk/design/design-guidelines.md
View File

@@ -4,7 +4,7 @@ description: Docker extension design
keywords: Docker, extensions, design
---
At Docker, we aim to build tools that integrate into a user's existing workflows rather than requiring them to adopt new ones. To that end, we strongly recommend that you follow these guidelines when building extensions. We will be reviewing and approving your Marketplace publication based on these requirements.
At Docker, we aim to build tools that integrate into a user's existing workflows rather than requiring them to adopt new ones. We strongly recommend that you follow these guidelines when building extensions. We review and approve your Marketplace publication based on these requirements.
Here is a simple checklist to go through when building your extension:
- Is it easy to get started?
@@ -18,43 +18,43 @@ Use the [Docker Material UI Theme](https://www.npmjs.com/package/@docker/docker-
- Ensure the extension has both a light and dark theme. Using the components and styles as per the Docker style guide ensures that your extension meets the [level AA accessibility standard.](https://www.w3.org/WAI/WCAG2AA-Conformance)
![light and dark mode](./images/light_dark_mode.png)
![light and dark mode](images/light_dark_mode.png)
<br>
- Ensure that your extension icon is visible both in light and dark mode.
![icon colors](./images/icon_colors.png)
![icon colors](images/icon_colors.png)
<br>
- Ensure that the navigational behaviour is consistent with the rest of Docker Desktop. Add a header to set the context for the extension.
- Ensure that the navigational behavior is consistent with the rest of Docker Desktop. Add a header to set the context for the extension.
![header](./images/header.png)
![header](images/header.png)
<br>
- The advantage we have with Docker Desktop over the CLI is that we have the opportunity to provide rich information to users. Make use of this interface as much as possible. Avoid embedding terminal windows.
- Avoid embedding terminal windows. The advantage we have with Docker Desktop over the CLI is that we have the opportunity to provide rich information to users. Make use of this interface as much as possible.
![terminal window dont](./images/terminal_window_dont.png){:height="=50%" width="50%"}
![terminal window dont](images/terminal_window_dont.png){:height="=50%" width="50%"}
![terminal window do](./images/terminal_window_do.png)
![terminal window do](images/terminal_window_do.png)
## Build Features Natively
- In order not to disrupt the flow of users, avoid scenarios where the user has to navigate outside Docker Desktop, to the CLI or a webpage for example, in order to carry out certain functionalities. Instead, build features that are native to Docker Desktop.
![switch context dont](./images/switch_context_dont.png){:height="=50%" width="50%"}
![switch context dont](images/switch_context_dont.png){:height="=50%" width="50%"}
![switch context do](./images/switch_context_do.png)
![switch context do](images/switch_context_do.png)
## Break Down Complicated User Flows
- If a flow is too complicated or the concept is abstract, break down the flow into multiple steps with one simple call-to-action in each step. This helps when onboarding novice users to your extension
![complicated flow](./images/complicated_flows.png)
![complicated flow](images/complicated_flows.png)
<br>
- Where there are multiple call-to-actions, ensure you use the primary (filled button style) and secondary buttons (outline button style) to convey the importance of each action.
![call to action](./images/cta.png)
![call to action](images/cta.png)
## Onboarding New Users
@@ -66,4 +66,10 @@ When building your extension, ensure that first time users of the extension and
- Link to necessary resources such as documentation.
- If your extension has particularly complex functionality, add a demo or video to the start page. This helps onboard a first time user quickly.
![start page](./images/start_page.png){:height="50%" width="50%"}
![start page](images/start_page.png){:height="50%" width="50%"}
## What's next?
- Explore our [design principles](design-principles.md).
- Take a look at our [UI styling guidelines](overview.md).
- Learn how to [publish your extension](../extensions/index.md).

9
desktop/extensions-sdk/design/design-principles.md
View File

@@ -1,5 +1,5 @@
---
title: Docker's design principles
title: Docker design principles
description: Docker extension design
keywords: Docker, extensions, design
---
@@ -22,4 +22,9 @@ We always provide clarity on what is happening and why. No amount of detail is w
## Scale with intention
Our products focus on inclusive growth and are continuously useful and adapt to match changing individual needs. We support all levels of expertise by meeting users where they are with conscious personalization.
<br>
<br>
## What's next?
- Take a look at our [UI styling guidelines](overview.md).
- Learn how to [publish your extension](../extensions/index.md).

11
desktop/extensions-sdk/design/mui-best-practices.md
View File

@@ -8,7 +8,7 @@ This article assumes you're following our recommended practice by using our [Mat
## Assume the theme can change at any time
Resist the temptation to fine-tune your UI with precise colors, offsets and font sizings to make it look as attractive as possible. Any specialisations you make today will be relative to the current MUI theme, and may look worse when the theme changes. Any part of the theme might change without warning, including (but not limited to):
Resist the temptation to fine-tune your UI with precise colors, offsets and font sizings to make it look as attractive as possible. Any specializations you make today will be relative to the current MUI theme, and may look worse when the theme changes. Any part of the theme might change without warning, including (but not limited to):
- The font, or font sizes
- Border thicknesses or styles
@@ -17,7 +17,7 @@ Resist the temptation to fine-tune your UI with precise colors, offsets and font
- The semantic colors (e.g. `error`, `primary`, `textPrimary`, etc) could be changed to use a different member of our palette
- Background colors (e.g. those of the page, or of dialogs) could change
- Spacings:
- The size of the basic unit of spacing,(exposed via `theme.spacing`. For instance, we may allow users to customise the density of the UI
- The size of the basic unit of spacing,(exposed via `theme.spacing`. For instance, we may allow users to customize the density of the UI
- The default spacing between paragraphs or grid items
The best way to build your UI, so that it’s robust against future theming changes, is to:
@@ -29,7 +29,7 @@ The best way to build your UI, so that it’s robust against future theming chan
- Write as little CSS as possible. Write semantic markup instead. For example, if you want to space out paragraphs of text, use the `paragraph` prop on your `Typography` instances. If you want to space out something else, use a `Stack` or `Grid` with the default spacing.
- Use visual idioms you’ve seen in the Docker Desktop UI, since these are the main ones we’ll test any theme changes against.
## When you go custom, centralise it
## When you go custom, centralize it
Sometimes you’ll need a piece of UI that doesn’t exist in our design system. If so, we recommend that you first reach out to us. We may already have something in our internal design system, or we may be able to expand our design system to accommodate your use case.
@@ -40,3 +40,8 @@ If you still decide to build it yourself after contacting us, try and define the
- A new [reuseable component](https://mui.com/material-ui/customization/how-to-customize/#2-reusable-component)
Some of the above options require you to extend our MUI theme. See the MUI documentation on [theme composition](https://mui.com/material-ui/customization/theming/#nesting-the-theme).
## What's next?
- Take a look at our [UI styling guide](overview.md).
- Learn how to [publish your extension](../extensions/index.md).

11
desktop/extensions-sdk/design/overview.md
View File

@@ -8,11 +8,11 @@ Our Design System is a constantly evolving set of specifications that aim to ens
We require extensions to match the wider Docker Desktop UI to a certain degree, and reserve the right to make this stricter in the future.
To get started on your UI, follow the below steps.
To get started on your UI, follow the steps below.
## 1. Choose your framework
### Preferred: React+MUI, using our theme
### Recommended: React+MUI, using our theme
Docker Desktop's UI is written in React and [MUI](https://mui.com/) (using Material UI to specific). This is the only officially supported framework for building extensions, and the one that our `init` command automatically configures for you. Using it brings significant benefits to authors:
@@ -21,7 +21,7 @@ Docker Desktop's UI is written in React and [MUI](https://mui.com/) (using Mater
Read our [MUI best practices](mui-best-practices.md) guide to learn future-proof ways to use MUI with Docker Desktop.
### Dispreferred: Some other framework
### Not recommended: Some other framework
You may prefer to use another framework, perhaps because you or your team are more familiar with it or because you have existing assets you want to reuse. This is possible, but highly discouraged. It means that:
@@ -42,3 +42,8 @@ With minor exceptions, displaying your logo for example, you should only use col
### Use counterpart colors in light/dark mode
Our colors have been chosen so that the counterpart colors in each variant of the palette should have the same essential characteristics. Anywhere you use `red-300` in light mode, you should use `red-300` in dark mode too.
## What's next?
- Take a look at our [MUI best practices](mui-best-practices.md).
- Learn how to [publish your extension](../extensions/index.md).

10
desktop/extensions-sdk/dev/api/overview.md
View File

@@ -27,9 +27,9 @@ export function App() {
The `ddClient` object gives access to various APIs:
- [Extension Backend](./backend.md)
- [Docker](./docker.md)
- [Dashboard](./dashboard.md)
- [Navigation](./dashboard-routes-navigation.md)
- [Extension Backend](backend.md)
- [Docker](docker.md)
- [Dashboard](dashboard.md)
- [Navigation](dashboard-routes-navigation.md)
Find the Extensions API reference [here](./reference/README.md).
Find the Extensions API reference [here](reference/README.md).

7
desktop/extensions-sdk/dev/oauth2-flow.md
View File

@@ -18,7 +18,7 @@ The Authorization Code grant type is used by confidential and public clients to
After the user returns to the client via the redirect URL, the application gets the authorization code from the URL and uses it to request an access token.
![oauth2-flow](./images/oauth2-flow.png){: style=width:80% }
![oauth2-flow](images/oauth2-flow.png){: style=width:80% }
The image above shows that:
- The Docker Extension asks the user to authorize access to their data.
@@ -37,7 +37,7 @@ Once the user enters the username and password, they are successfully authentica
From the extension UI, you can provide a button that, when selected, opens a new window in a browser to authenticate the user.
Use the [ddClient.host.openExternal](https://docs.docker.com/desktop/extensions-sdk/dev/api/dashboard/#open-a-url) API to open a browser to the auth URL. For example:
Use the [ddClient.host.openExternal](api/dashboard.md#open-a-url) API to open a browser to the auth URL. For example:
```typescript
window.ddClient.openExternal("https://authorization-server.com/authorize?
@@ -107,3 +107,6 @@ It is highly recommended that you use an external source of storage to store the
>
> Storing the access token in a client's localStorage is a security risk as that storage is currently shared amongst all extensions.
{: .warning}
## What's next
Learn how to [publish and distribute your extension](../extensions/index.md)

62
desktop/extensions-sdk/dev/overview.md
View File

@@ -1,62 +0,0 @@
---
title: Overview
description: Docker extension development
keywords: Docker, extensions, sdk, development
---
The section below describes how to get started developing your custom Docker extension.
Extensions can be composed of a visual part displayed in the Docker Desktop dashboard, and one or more optional services that run inside the Docker Desktop VM.
If you intend to develop an extension which consists exclusively of a visual part with no services running in the VM, see the [React extension](../tutorials/react-extension.md) tutorial.
If your extension needs to invoke docker commands, see the [Docker cli extension](../tutorials/minimal-frontend-using-docker-cli.md) tutorial.
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) example.
For further inspiration, see the other examples in the [samples folder](https://github.com/docker/extensions-sdk/tree/main/samples)
### Open Dev Tools
In order to open the Chrome Dev Tools for your extension when you click on the extension tab, run:
```console
$ docker extension dev debug john/my-extension
```
Each subsequent click on the extension tab will also open Chrome Dev Tools.
To stop this behaviour, run:
```console
$ docker extension dev reset john/my-extension
```
After an extension is deployed, it is also possible to open the Chrome Dev Tools from the UI extension part using a variation of the [Konami Code](https://en.wikipedia.org/wiki/Konami_Code).
Click on the extension tab, and then hit the key sequence `up, up, down, down, left, right, left, right, p, d, t`.
### Develop the Extension UI
If your extension has a UI, you can see it directly inside Docker Desktop whilst you develop it directly.
For this you need to first install the extension.
If you then run a development server locally, with `yarn start` for example, enter the following command:
```console
$ docker extension dev ui-source john/my-extension http://localhost:8080
```
This changes the source of the extension UI to your local development server. Auto and hot-reload now work.
> Make sure to reopen the Dashboard when you set a new source for the extension's UI.
Once finished, you can reset the extension configuration to the original settings. This will also reset opening Chrome dev tools if you used `docker extension dev debug my-extension`:
```console
$ docker extension dev reset john/my-extension
```
## Show the extension containers
If your extension is composed of one or more services running as containers in the Docker Desktop VM, you can access them easily from the dashboard in Docker Desktop.
1. In Docker Desktop, navigate to **Settings**, or **Preferences** if you're a Mac user.
2. Under the **Extensions** tab, select the **Show Docker Desktop Extensions system containers** option. You can now view your extension containers and their logs.

2
desktop/extensions-sdk/dev/cli/usage.md → desktop/extensions-sdk/dev/usage.md
View File

@@ -2,6 +2,8 @@
title: Usage overview
description: Docker extension CLI
keywords: Docker, extensions, sdk, CLI
redirect_from:
- /desktop/extensions-sdk/dev/cli/usage/
---
The Extensions CLI is an extension development tool that is used to manage Docker extensions. Actions include install, list, remove, and validate extensions.

7
desktop/extensions-sdk/extensions/DISTRIBUTION.md
View File

@@ -18,7 +18,7 @@ The image must have [several labels](labels.md):
Packaging and releasing an extension is done by running `docker build` to create the image, and `docker push` to make the image available on Docker Hub with a specific tag that allows you to manage versions of the extension.
Take advantage of multi-arch images to build images that include ARM/AMD binaries. The right image will be used for Mac users depending on their architecture.
For extensions on Docker Desktop for Windows, Windows binaries that are to be installed on the host must be included in the same extension image. We will revisit this with some tag conventions to allow some images specific to Windows, and other images specific to Mac, based on a tag prefix. See [how to build extensions for multiple architectures](./multi-arch.md).
For extensions on Docker Desktop for Windows, Windows binaries that are to be installed on the host must be included in the same extension image. We will revisit this with some tag conventions to allow some images specific to Windows, and other images specific to Mac, based on a tag prefix. See [how to build extensions for multiple architectures](multi-arch.md).
You can implement extensions without any constraints on the code repository. Docker does not need access to the code repository in order to use the extension. Release of new versions of the extension is managed you.
@@ -38,11 +38,6 @@ Docker Desktop scans the list of published extensions for new versions regularly
Users can download and install the newer version of an extension without updating Docker Desktop itself.
## Publish your extension in the Marketplace
Docker Desktop displays published extensions in the Extensions Marketplace.
If you want your extension to be published in the Marketplace, you can submit your extension [here](https://www.docker.com/products/extensions/submissions/). We'll review your submission and provide feedback if changes are needed before we can validate and publish it to make it available to all Docker Desktop users.
## API dependencies
Extensions must specify the Extension API version they rely on. Currently there is no technical validation of this version, as the extension framework is still experimental.

47
desktop/extensions-sdk/extensions/index.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: Publish your extension
description: General steps in how to publish an extension
keywords: Docker, Extensions, sdk, publish
---
To publish the extension, upload the Docker image to [DockerHub](https://hub.docker.com/).
Tag the previous image to prepend the account owner at the beginning of the image name:
`docker tag <name-of-your-extension> owner/<name-of-your-extension>`
Push the image to Docker Hub:
`docker push owner/<name-of-your-extension>`
> Note
>
> For Docker Extensions images to be listed in Docker Desktop, they must be approved by Docker and the tags must follow semantic versioning, e.g: `0.0.1`.
>
> See [distribution and new releases](DISTRIBUTION.md#distribution-and-new-releases) for more information.
>
> See [semver.org](https://semver.org/) to learn more about semantic versioning.
>
> Having trouble pushing the image?
>
> Ensure you are logged into DockerHub. Otherwise, run `docker login` to authenticate.
>
## Publish your extension in the Marketplace
Docker Desktop displays published extensions in the Extensions Marketplace.
If you want your extension to be published in the Marketplace, you can submit your extension [here](https://www.docker.com/products/extensions/submissions/). We'll review your submission and provide feedback if changes are needed before we can validate and publish it to make it available to all Docker Desktop users.
## Clean up
To remove the extension, run:
`docker extension rm <name-of-your-extension>`
## What's next
Find more information about:
- [The `metadata.json` file](METADATA.md)
- [Labels in your `Dockerfile`](labels.md)
- [Distributing your extension](DISTRIBUTION.md)
- [Building extensions for multiple architectures](multi-arch.md)

46
desktop/extensions-sdk/extensions/multi-arch.md
View File

@@ -1,48 +1,50 @@
---
title: Building multi-arch extensions
description: Docker extension multi-arch
keywords: Docker, extensions, sdk, multi-arch
title: Build the extensions for multiple architectures
description: Step three in creating an extension.
keywords: Docker, Extensions, sdk, build, multi-arch
---
## Introduction
At a minimum, you must ensure your extension is supported for the following architectures:
It is highly recommended that, at a minimum, your extension is supported for the following architectures:
- `linux/amd64`
- `linux/arm64`
Docker Desktop retrieves the extension image according to the user's system architecture. If the extension does not provide an image that matches the user's system architecture, Docker Desktop is not able to install the extension. As a result, users can't run the extension in Docker Desktop.
Docker Desktop retrieves the extension image according to the user’s system architecture. If the extension does not provide an image that matches the user’s system architecture, Docker Desktop is not able to install the extension. As a result, users can’t run the extension in Docker Desktop.
## Building and pushing for multiple architectures
### Build and push for multiple architectures
If you created an extension from the `docker extension init` command, there's a `Makefile` at the root of the directory that includes a target with name `push-extension`.
If you created an extension from the `docker extension init` command, the `Makefile` at the root of the directory includes a target with name `push-extension`.
You can do `make push-extension` to build your extension against both `linux/amd64` and `linux/arm64` platforms, and push them to DockerHub.
You can do `make push-extension` to build your extension against both `linux/amd64` and `linux/arm64` platforms, and push them to DockerHub. For example:
Alternatively, if you do not want to use the provided `Makefile`, you can use the command below to build your extension for multiple architectures:
`docker buildx build --platform=linux/amd64,linux/arm64 -t <name-of-your-extension> .`
```cli
Alternatively, if you started from an empty directory, use the command below to build your extension for multiple architectures:
```
docker buildx build \
--push \
--platform=linux/amd64,linux/arm64 \
--tag=my-extension:0.0.1 .
```
The information above serves as a guide to help you get started. It's up to you to define the CI/CD process to build and push the extension.
The information above serves as a guide to help you get started. It’s up to you to define the CI/CD process to build and push the extension.
![hub-multi-arch-extension](./images/hub-multi-arch-extension.png)
![hub-multi-arch-extension](images/hub-multi-arch-extension.png)
## Adding multi-arch binaries
### Adding multi-arch binaries
If your extension includes some binaries that deploy to the host, it's important that they also have the right architecture when building the extension against multiple architectures.
If your extension includes some binaries that deploy to the host, it’s important that they also have the right architecture when building the extension against multiple architectures.
Currently, Docker does not provide a way to explicitly specify multiple binaries for every architecture in the `metadata.json` file. However, you can add architecture-specific binaries depending on the `TARGETARCH` in the extension's `Dockerfile`.
Currently, Docker does not provide a way to explicitly specify multiple binaries for every architecture in the `metadata.json` file. However, you can add architecture-specific binaries depending on the `TARGETARCH` in the extension’s `Dockerfile`.
The example below shows an extension that uses a binary as part of its operations. The extension needs to run both in Docker Desktop for Mac and Windows.
In the `Dockerfile`, we download the binary depending on the target architecture:
```Dockerfile
#syntax=docker/dockerfile:1.3-labs
FROM alpine AS dl
@@ -104,15 +106,17 @@ In the `metadata.json` file, we specify the path for every binary on every platf
As a result, when `TARGETARCH` equals:
- `arm64`, the `kubectl` binary fetched corresponds to the `arm64` architecture, and is copied to `/darwin/kubectl` in the final stage.
- `amd64`, two `kubectl` binaries are fetched. One for Darwin and another for Windows. They are copied to `/darwin/kubectl` and `/windows/kubectl.exe` respectively, in the final stage.
> Note that the binary destination path for `darwin` is `darwin/kubectl` in both cases. The only change is the architecture-specific binary that is downloaded.
> Note
>
> The binary destination path for darwin is darwin/kubectl in both cases. The only change is the architecture-specific binary that is downloaded.
When the extension is installed, the extension framework copies the binaries from the extension image at `/darwin/kubectl` for Darwin, or `/windows/kubectl.exe` for Windows, to a specific location in the user's host filesystem.
When the extension is installed, the extension framework copies the binaries from the extension image at `/darwin/kubectl` for Darwin, or `/windows/kubectl.exe` for Windows, to a specific location in the user’s host filesystem.
## FAQs
- Can I develop extensions that run Windows containers?
### Can I develop extensions that run Windows containers?
Although Docker Extensions is supported on Docker Desktop for Windows, Mac, and Linux, the extension framework only supports linux containers. Therefore, you must target `linux` as the OS when you build your extension image.

27
desktop/extensions-sdk/extensions/validation.md
View File

@@ -1,27 +0,0 @@
---
title: Validate your extension
description: Docker extension validaiton
keywords: Docker, extensions, sdk, validation
---
The Extensions CLI lets you validate your extension before installing and running it locally:
```console
$ docker extension validate my-extension
```
It checks the content of the image and ensures the image has the right labels needed for extensions.
Before the image is built, it is also possible to validate only the metadata.json file:
```console
$ docker extension validate /path/to/metadata.json
```
## JSON schema
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).
## Labels
See [labels](labels.md).

104
desktop/extensions-sdk/index.md
View File

@@ -1,7 +1,9 @@
---
title: Introduction
title: Overview
description: Overall index for Docker Extensions SDK documentation
keywords: Docker, Extensions, sdk
redirect_from:
- /desktop/extensions-sdk/dev/overview/
---
Use the resources in this section to create your own Docker Extension.
@@ -11,8 +13,6 @@ Use the resources in this section to create your own Docker Extension.
> The Docker Extensions SDK is currently in Beta.
> Features and APIs detailed below are subject to change.
## Overview
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](extensions/METADATA.md).
@@ -20,81 +20,43 @@ An extension can contain a UI part and backend parts that run either on the host
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.
## Prerequisites
## How to use the resources in this section
Before you create your own extension, you need a specific Docker Desktop build that comes with extension capabilities.
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.
From the [releases page](https://github.com/docker/extensions-sdk/releases/latest), install the Extensions CLI which is used to manage extensions later on.
### Part one: Build the foundations
> Using the CLI to install unpublished extensions
The build process consists of:
- Installing the prerequisites.
- 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.
- 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](dev/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
>
> Extensions can install binaries, invoke commands and access files on your machine. Make sure you trust extensions before installing them on your machine.
> {: .warning}
>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).
Once you've downloaded the Extensions CLI, extract the binary in to `~/.docker/cli-plugins`.
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) example.
In your terminal, run:
For further inspiration, see the other examples in the [samples folder](https://github.com/docker/extensions-sdk/tree/main/samples)
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#prereq-macos-intel">MacOS (intel)</a></li>
<li><a data-toggle="tab" data-target="#prereq-macos-m1">MacOS (M1)</a></li>
<li><a data-toggle="tab" data-target="#prereq-windows">Windows</a></li>
<li><a data-toggle="tab" data-target="#prereq-wsl2">WSL2</a></li>
<li><a data-toggle="tab" data-target="#prereq-linux">Linux</a></li>
</ul>
<div class="tab-content">
<div id="prereq-macos-intel" class="tab-pane fade in active" markdown="1">
```console
$ tar -xvzf desktop-extension-cli-darwin-amd64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
### Part two: Publish and distribute your extension
<hr></div>
<div id="prereq-macos-m1" class="tab-pane fade" markdown="1">
```console
$ tar -xvzf desktop-extension-cli-darwin-arm64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
Docker Desktop displays published extensions in the Extensions Marketplace. If you want your extension to be published in the Marketplace, you can submit your extension [here](https://www.docker.com/products/extensions/submissions/). We’ll review your submission and provide feedback if changes are needed before we can validate and publish it to make it available to all Docker Desktop users.
<hr></div>
<div id="prereq-windows" class="tab-pane fade" markdown="1">
```console
PS> tar -xvzf desktop-extension-cli-windows-amd64.tar.gz
PS> mkdir -p ~/.docker/cli-plugins
PS> mv docker-extension.exe ~/.docker/cli-plugins
```
## What’s next?
If you want to get up and running quickly with a Docker Extension, see the [Quickstart guide](quickstart.md).
<hr></div>
<div id="prereq-wsl2" class="tab-pane fade" markdown="1">
```console
$ tar -xvzf desktop-extension-cli-linux-amd64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
<hr></div>
<div id="prereq-linux" class="tab-pane fade" markdown="1">
```console
$ tar -xvzf desktop-extension-cli-linux-amd64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
<hr></div>
</div>
You can now list installed extensions (the list should be empty if you have not installed extensions already):
```console
$ docker extension ls
ID PROVIDER VERSION UI VM HOST
```
![Extensions enabled](images/extensions-enabled.png)
For more in-depth information about each step of the extension creation process, see [Get started](/build/get-started.md).

132
desktop/extensions-sdk/quickstart.md Normal file
View File

@@ -0,0 +1,132 @@
---
title: Quickstart
description: Guide on how to build an extension quickly
keywords: quickstart, extensions
---
Follow the guide below to build a basic Docker Extension quickly. The Quickstart guide automatically generates boilerplate files for you.
>Note
>
>NodeJS and Go are only required when you follow the quickstart guide to build an extension. It uses the `docker extension init` command to automatically generate boilerplate files. This command uses a template based on a ReactJS and Go application.
## Prerequisites
- [Docker Desktop](../release-notes.md)
- [NodeJS](https://nodejs.org/)
- [Go](https://go.dev/dl/)
- [Extensions CLI](https://github.com/docker/extensions-sdk/releases/latest)
Once you've downloaded the Extensions CLI, extract the binary in to `~/.docker/cli-plugins`.
In your terminal, run:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#prereq-macos-intel">MacOS (intel)</a></li>
<li><a data-toggle="tab" data-target="#prereq-macos-m1">MacOS (M1)</a></li>
<li><a data-toggle="tab" data-target="#prereq-windows">Windows</a></li>
<li><a data-toggle="tab" data-target="#prereq-wsl2">WSL2</a></li>
<li><a data-toggle="tab" data-target="#prereq-linux">Linux</a></li>
</ul>
<div class="tab-content">
<div id="prereq-macos-intel" class="tab-pane fade in active" markdown="1">
```console
$ tar -xvzf desktop-extension-cli-darwin-amd64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
<hr></div>
<div id="prereq-macos-m1" class="tab-pane fade" markdown="1">
```console
$ tar -xvzf desktop-extension-cli-darwin-arm64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
<hr></div>
<div id="prereq-windows" class="tab-pane fade" markdown="1">
```console
PS> tar -xvzf desktop-extension-cli-windows-amd64.tar.gz
PS> mkdir -p ~/.docker/cli-plugins
PS> mv docker-extension.exe ~/.docker/cli-plugins
```
<hr></div>
<div id="prereq-wsl2" class="tab-pane fade" markdown="1">
```console
$ tar -xvzf desktop-extension-cli-linux-amd64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
<hr></div>
<div id="prereq-linux" class="tab-pane fade" markdown="1">
```console
$ tar -xvzf desktop-extension-cli-linux-amd64.tar.gz
$ mkdir -p ~/.docker/cli-plugins
$ mv docker-extension ~/.docker/cli-plugins
```
<hr></div>
</div>
## Step one: Set up your directory
To set up your directory, use the `init` subcommand and provide a name for your extension.
`docker extension init my-extension`
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 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.
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:
`docker build -t <name-of-your-extension> .`
`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:
`? Hub repository (eg. namespace/repository on hub): john/my-extension`
The `docker build` generates an image with name `john/my-extension`.
## Step three: Install and preview the extension
To install the extension in Docker Desktop, run:
`docker extension install <name-of-your-extension>`
To preview the extension in Docker Desktop, close and 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.
## Step four: Submit and publish your extension to the Marketplace
If you want to make your extension available to all Docker Desktop users, you can submit it for publication in the Marketplace. For more information, see [Publish](extensions/index.md).
## Clean up
To remove the extension, run:
`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](dev/oauth2-flow.md)
- [Designing the UI](design/design-guidelines.md)