mirror of https://github.com/docker/docs.git
Move files from extensions-sdk repo to this repo, to author docs in one place (#14903)
Signed-off-by: Guillaume Tardif <guillaume.tardif@gmail.com>
This commit is contained in:
Guillaume Tardif
GitHub
parent
3eec335931
commit
362614bb6f
|
|
@ -45,7 +45,7 @@ compose_file_v3: "3.9"
|
|||
compose_file_v2: "2.4"
|
||||
machine_version: "0.16.0"
|
||||
distribution_version: "2.7"
|
||||
compose_switch_version: "1.0.4"
|
||||
compose_switch_version: "1.0.4"
|
||||
|
||||
# Options for displaying minimum API version requirements in the reference pages.
|
||||
#
|
||||
|
|
@ -150,13 +150,6 @@ fetch-remote:
|
|||
- "!docs/README.md" # readme to make things nice in the compose-cli repo, but meaningless here
|
||||
- "!docs/architecture.md" # Compose-CLI architecture, unrelated to cloud integration
|
||||
|
||||
- repo: "https://github.com/docker/extensions-sdk"
|
||||
ref: "main"
|
||||
paths:
|
||||
- dest: "desktop/extensions-sdk"
|
||||
src:
|
||||
- "docs/**"
|
||||
|
||||
- repo: "https://github.com/distribution/distribution"
|
||||
ref: "release/2.7"
|
||||
paths:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
title: Design guidelines
|
||||
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.
|
||||
|
||||
Here is a simple checklist to go through when building your extension:
|
||||
- Is it easy to get started?
|
||||
- Is it easy to use?
|
||||
- Is it easy to get help when needed?
|
||||
|
||||
|
||||
## Build a consistent experience with Docker Desktop.
|
||||
|
||||
Use the [Docker Material UI Theme](https://www.npmjs.com/package/@docker/docker-mui-theme) and the [Docker Extensions Styleguide](https://www.figma.com/file/U7pLWfEf6IQKUHLhdateBI/Docker-Design-Guidelines?node-id=1%3A28771) to ensure that your extension feels like it is part of Docker Desktop to create a seamless experience for users.
|
||||
|
||||
- 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)
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
- Ensure that your extension icon is visible both in light and dark mode.
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
- Ensure that the navigational behaviour is consistent with the rest of Docker Desktop. Add a header to set the context for the extension.
|
||||
|
||||
|
||||
<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.
|
||||
|
||||
{:height="=50%" width="50%"}
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
{:height="=50%" width="50%"}
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
<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.
|
||||
|
||||
|
||||
|
||||
## Onboarding New Users
|
||||
|
||||
When building your extension, ensure that first time users of the extension and your product can understand its value-add and adopt it easily. Ensure you include contextual help within the extension.
|
||||
|
||||
- Ensure that all necessary information is added to the extensions Marketplace as well as the extensions detail page. This should include:
|
||||
- Screenshots of the extension.
|
||||
- A detailed description that covers what the purpose of the extension is, who would find it useful and how it works.
|
||||
- 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.
|
||||
|
||||
{:height="50%" width="50%"}
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
---
|
||||
title: Docker's design principles
|
||||
description: Docker extension design
|
||||
keywords: Docker, extensions, design
|
||||
---
|
||||
|
||||
## Provide actionable guidance
|
||||
We anticipate needs and provide simple explanations with clear actions so people are never lost and always know what to do next. Recommendations lead users to functionality that enhances the experience and extends their knowledge.
|
||||
<br>
|
||||
|
||||
## Create value through confidence
|
||||
People from all levels of experience should feel they know how to use our product. Experiences are familiar, unified, and easy to use so all users feel like experts.
|
||||
<br>
|
||||
|
||||
## Infuse productivity with delight
|
||||
We seek out moments of purposeful delight that elevate rather than distract, making work easier and more gratifying. Simple tasks are automated and users are left with more time for innovation.
|
||||
<br>
|
||||
|
||||
## Build trust through transparency
|
||||
We always provide clarity on what is happening and why. No amount of detail is withheld; the right information is shown at the right time and is always accessible.
|
||||
<br>
|
||||
|
||||
## 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>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 74 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 68 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 81 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 134 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
title: MUI best practices
|
||||
description: Guidelines for using MUI to maximise compatibility with Docker Desktop
|
||||
keywords: Docker, extensions, mui, theme, theming, material-ui, material
|
||||
---
|
||||
|
||||
This article assumes you're following our recommended practice by using our [Material UI theme](https://www.npmjs.com/package/@docker/docker-mui-theme). Following the steps below maximises compatibility with Docker Desktop and minimises the work you need to do as an extension author. They should be considered supplementary to the non-MUI-specific guidelines found in the [UI Styling overview](overview.md).
|
||||
|
||||
## 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):
|
||||
|
||||
- The font, or font sizes
|
||||
- Border thicknesses or styles
|
||||
- Colors:
|
||||
- Our palette members (e.g. `red-100`) could change their RGB values
|
||||
- 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 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:
|
||||
|
||||
- Override the default styling as little as possible.
|
||||
- Use semantic typography. e.g. use `Typography`s or `Link`s with appropriate `variant`s instead of using typographical HTML elements (`<a>`, `<p>`, `<h1>`, etc) directly.
|
||||
- Use canned sizes. e.g. use `size="small"` on buttons, or `fontSize="small"` on icons, instead of specifying sizes in pixels.
|
||||
- Prefer semantic colors. e.g. use `error` or `primary` over explicit color codes.
|
||||
- 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
|
||||
|
||||
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.
|
||||
|
||||
If you still decide to build it yourself after contacting us, try and define the new UI in a reuseable fashion. If you define your custom UI in just one place, it’ll make it easier to change in the future if our core theme changes. You could use:
|
||||
|
||||
- A new `variant` of an existing component - see [MUI docs](https://mui.com/material-ui/customization/theme-components/#creating-new-component-variants)
|
||||
- A MUI mixin (a freeform bundle of reuseable styling rules defined inside a theme)
|
||||
- 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).
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: UI styling overview
|
||||
description: Docker extension design
|
||||
keywords: Docker, extensions, design
|
||||
---
|
||||
|
||||
Our Design System is a constantly evolving set of specifications that aim to ensure visual consistency across Docker products, and meet [level AA accessibility standards](https://www.w3.org/WAI/WCAG2AA-Conformance). We've opened parts of it to extension authors, documenting basic styles (color, typography) and components. See: [Docker Extensions Styleguide](https://www.figma.com/file/U7pLWfEf6IQKUHLhdateBI/Docker-Design-Guidelines?node-id=1%3A28771).
|
||||
|
||||
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.
|
||||
|
||||
## 1. Choose your framework
|
||||
|
||||
### Preferred: 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:
|
||||
|
||||
- You can use our [Material UI theme](https://www.npmjs.com/package/@docker/docker-mui-theme) to automatically replicate Docker Desktop's look & feel.
|
||||
- In future, we'll release utilities and components specifically targeting this combination (e.g. custom MUI components, or React hooks for interacting with Docker).
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
- You'll need to manually replicate the look and feel of Docker Desktop. This will take a lot of effort, and if you don't match our theme closely enough, users will find your extension jarring and we may ask you to make changes during a review process.
|
||||
- You'll have a higher maintenance burden. Whenever Docker Desktop's theme changes (which could happen in any release), you'll need to manually change your extension to match it.
|
||||
- If your extension is open-source, deliberately avoiding common conventions will make it harder for the community to contribute to it.
|
||||
|
||||
## 2. Follow the below recommendations
|
||||
|
||||
### Follow our MUI best practices (if applicable)
|
||||
|
||||
See our [MUI best practices](mui-best-practices.md) article.
|
||||
|
||||
### Only use colors from our palette
|
||||
|
||||
With minor exceptions, displaying your logo for example, you should only use colors from our palette. These can be found in our [style guide document](https://www.figma.com/file/U7pLWfEf6IQKUHLhdateBI/Docker-Design-Guidelines?node-id=1%3A28771), and will also soon be available in our MUI theme and via CSS variables.
|
||||
|
||||
### 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.
|
||||
|
|
@ -0,0 +1,172 @@
|
|||
---
|
||||
title: Extension Backend
|
||||
description: Docker extension API
|
||||
keywords: Docker, extensions, sdk, API
|
||||
---
|
||||
|
||||
The `ddClient.extension.vm` object can be used to communicate with the backend defined in the [vm section](../../extensions/METADATA.md#vm-section) of the extension metadata.
|
||||
|
||||
## get
|
||||
|
||||
▸ **get**(`url`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP GET request to a backend service.
|
||||
|
||||
```typescript
|
||||
ddClient.extension.vm.service
|
||||
.get("/some/service")
|
||||
.then((value: any) => console.log(value)
|
||||
```
|
||||
|
||||
See [Service API Reference](reference/interfaces/HttpService.md) for other methods such as POST, UPDATE, and DELETE.
|
||||
|
||||
> Deprecated extension backend communication
|
||||
>
|
||||
> The methods below that use `window.ddClient.backend` are deprecated and will be removed in a future version. Use the methods specified above.
|
||||
|
||||
The `window.ddClient.backend` object can be used to communicate with the backend
|
||||
defined in the [vm section](../../extensions/METADATA.md#vm-section) of the
|
||||
extension metadata. The client is already connected to the backend.
|
||||
|
||||
Example usages:
|
||||
|
||||
```typescript
|
||||
window.ddClient.backend
|
||||
.get("/some/service")
|
||||
.then((value: any) => console.log(value));
|
||||
|
||||
window.ddClient.backend
|
||||
.post("/some/service", { ... })
|
||||
.then((value: any) => console.log(value));
|
||||
|
||||
window.ddClient.backend
|
||||
.put("/some/service", { ... })
|
||||
.then((value: any) => console.log(value));
|
||||
|
||||
window.ddClient.backend
|
||||
.patch("/some/service", { ... })
|
||||
.then((value: any) => console.log(value));
|
||||
|
||||
window.ddClient.backend
|
||||
.delete("/some/service")
|
||||
.then((value: any) => console.log(value));
|
||||
|
||||
window.ddClient.backend
|
||||
.head("/some/service")
|
||||
.then((value: any) => console.log(value));
|
||||
|
||||
window.ddClient.backend
|
||||
.request({ url: "/url", method: "GET", headers: { 'header-key': 'header-value' }, data: { ... }})
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
## Run a command in the extension backend container
|
||||
|
||||
For example, execute the command `ls -l` inside the backend container:
|
||||
|
||||
```typescript
|
||||
await ddClient.extension.vm.cli.exec("ls", ["-l"]);
|
||||
```
|
||||
|
||||
Stream the output of the command executed in the backend container. For example, spawn the command `ls -l` inside the backend container:
|
||||
|
||||
```typescript
|
||||
await ddClient.extension.vm.cli.exec("ls", ["-l"], {
|
||||
stream: {
|
||||
onOutput(data) {
|
||||
if (data.stdout) {
|
||||
console.error(data.stdout);
|
||||
} else {
|
||||
console.log(data.stderr);
|
||||
}
|
||||
},
|
||||
onError(error) {
|
||||
console.error(error);
|
||||
},
|
||||
onClose(exitCode) {
|
||||
console.log("onClose with exit code " + exitCode);
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
For more details, refer to the [Extension VM API Reference](reference/interfaces/ExtensionVM.md)
|
||||
|
||||
> Deprecated extension backend command execution
|
||||
>
|
||||
> This method is deprecated and will be removed in a future version. Use the specified method above.
|
||||
|
||||
If your extension ships with additional binaries that should be run inside the
|
||||
backend container, you can use the `execInVMExtension` function:
|
||||
|
||||
```typescript
|
||||
const output = await window.ddClient.backend.execInVMExtension(
|
||||
`cliShippedInTheVm xxx`
|
||||
);
|
||||
console.log(output);
|
||||
```
|
||||
|
||||
## Invoke an extension binary on the host
|
||||
|
||||
You can run binaries defined in the [host section](../../extensions/METADATA.md#host-section)
|
||||
of the extension metadata.
|
||||
|
||||
For example, execute the shipped binary `kubectl -h` command in the host:
|
||||
|
||||
```typescript
|
||||
await ddClient.extension.host.cli.exec("kubectl", ["-h"]);
|
||||
```
|
||||
|
||||
As long as the `kubectl` binary is shipped as part of your extension, you can spawn the `kubectl -h` command in the host and get the output stream:
|
||||
|
||||
```typescript
|
||||
await ddClient.extension.host.cli.exec("kubectl", ["-h"], {
|
||||
stream: {
|
||||
onOutput(data: { stdout: string } | { stderr: string }): void {
|
||||
if (data.stdout) {
|
||||
console.error(data.stdout);
|
||||
} else {
|
||||
console.log(data.stderr);
|
||||
}
|
||||
},
|
||||
onError(error: any): void {
|
||||
console.error(error);
|
||||
},
|
||||
onClose(exitCode: number): void {
|
||||
console.log("onClose with exit code " + exitCode);
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
You can stream the output of the command executed in the backend container or in the host.
|
||||
|
||||
For more details, refer to the [Extension Host API Reference](reference/interfaces/ExtensionHost.md)
|
||||
|
||||
> Deprecated invocation of extension binary
|
||||
>
|
||||
> This method is deprecated and will be removed in a future version. Use the method specified above.
|
||||
|
||||
To execute a command in the host:
|
||||
|
||||
```typescript
|
||||
window.ddClient.execHostCmd(`cliShippedOnHost xxx`).then((cmdResult: any) => {
|
||||
console.log(cmdResult);
|
||||
});
|
||||
```
|
||||
|
||||
To stream the output of the command executed in the backend container or in the host:
|
||||
|
||||
```typescript
|
||||
window.ddClient.spawnHostCmd(
|
||||
`cliShippedOnHost`,
|
||||
[`arg1`, `arg2`],
|
||||
(data: any, err: any) => {
|
||||
console.log(data.stdout, data.stderr);
|
||||
// Once the command exits we get the status code
|
||||
if (data.code) {
|
||||
console.log(data.code);
|
||||
}
|
||||
}
|
||||
);
|
||||
```
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
title: Navigation
|
||||
description: Docker extension API
|
||||
keywords: Docker, extensions, sdk, API
|
||||
---
|
||||
|
||||
`ddClient.desktopUI.navigate` enables navigation to specific screens of Docker Desktop such as the containers tab, the images tab, or a specific container's logs.
|
||||
|
||||
For example, navigate to a given container logs:
|
||||
|
||||
```typescript
|
||||
await ddClient.desktopUI.navigate.viewContainerLogs(id);
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
For more details about all navigation methods, see the [Navigation API reference](reference/interfaces/NavigationIntents.md).
|
||||
|
||||
> Deprecated navigation methods
|
||||
>
|
||||
> These methdos are deprecated and will be removed in a future version. Use the methods specified above.
|
||||
|
||||
```typescript
|
||||
window.ddClient.navigateToContainers();
|
||||
// id - the full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`
|
||||
window.ddClient.navigateToContainer(id);
|
||||
window.ddClient.navigateToContainerLogs(id);
|
||||
window.ddClient.navigateToContainerInspect(id);
|
||||
window.ddClient.navigateToContainerStats(id);
|
||||
|
||||
window.ddClient.navigateToImages();
|
||||
window.ddClient.navigateToImage(id, tag);
|
||||
|
||||
window.ddClient.navigateToVolumes();
|
||||
window.ddClient.navigateToVolume(volume);
|
||||
|
||||
window.ddClient.navigateToDevEnvironments();
|
||||
```
|
||||
|
|
@ -0,0 +1,95 @@
|
|||
---
|
||||
title: Dashboard
|
||||
description: Docker extension API
|
||||
keywords: Docker, extensions, sdk, API
|
||||
---
|
||||
|
||||
## User notifications
|
||||
|
||||
Toasts provide a brief notification to the user. They appear temporarily and
|
||||
shouldn't interrupt the user experience. They also don't require user input to disappear.
|
||||
|
||||
### success
|
||||
|
||||
▸ **success**(`msg`): `void`
|
||||
|
||||
Use to display a toast message of type success.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.toast.success("message");
|
||||
```
|
||||
|
||||
### warning
|
||||
|
||||
▸ **warning**(`msg`): `void`
|
||||
|
||||
Use to display a toast message of type warning.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.toast.warning("message");
|
||||
```
|
||||
|
||||
### error
|
||||
|
||||
▸ **error**(`msg`): `void`
|
||||
|
||||
Use to display a toast message of type error.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.toast.error("message");
|
||||
```
|
||||
|
||||
For more details about method parameters and the return types available, see [Toast API reference](reference/interfaces/Toast.md).
|
||||
|
||||
> Deprecated user notifications
|
||||
>
|
||||
> These methods are deprecated and will be removed in a future version. Use the methods specified above.
|
||||
|
||||
```typescript
|
||||
window.ddClient.toastSuccess("message");
|
||||
window.ddClient.toastWarning("message");
|
||||
window.ddClient.toastError("message");
|
||||
```
|
||||
|
||||
## Open a file selection dialog
|
||||
|
||||
This function opens a file selector dialog that asks the user to select a file or folder.
|
||||
|
||||
▸ **showOpenDialog**(`dialogProperties`): `Promise`<[`OpenDialogResult`](reference/interfaces/OpenDialogResult.md)\>:
|
||||
|
||||
The `dialogProperties` parameter is a list of flags passed to Electron to customize the dialog's behaviour. For example, you can pass `multiSelections` to allow a user to select multiple files. See [Electron's documentation](https://www.electronjs.org/docs/latest/api/dialog) for a full list.
|
||||
|
||||
```typescript
|
||||
const result = await ddClient.desktopUI.dialog.showOpenDialog({
|
||||
properties: ["openDirectory"],
|
||||
});
|
||||
if (!result.canceled) {
|
||||
console.log(result.paths);
|
||||
}
|
||||
```
|
||||
|
||||
## Open a URL
|
||||
|
||||
This function opens an external URL with the system default browser.
|
||||
|
||||
▸ **openExternal**(`url`): `void`
|
||||
|
||||
```typescript
|
||||
ddClient.host.openExternal("https://docker.com");
|
||||
```
|
||||
|
||||
> The URL must have the protocol `http` or `https`.
|
||||
|
||||
For more details about method parameters and the return types available, see [Desktop host API reference](reference/interfaces/Host.md).
|
||||
|
||||
> Deprecated user notifications
|
||||
>
|
||||
> This method is deprecated and will be removed in a future version. Use the methods specified above.
|
||||
|
||||
```typescript
|
||||
window.ddClient.openExternal("https://docker.com");
|
||||
```
|
||||
|
||||
## Navigation to Dashboard routes
|
||||
|
||||
From your extension, you can also [navigate](dashboard-routes-navigation.md) to other parts of the Docker Desktop Dashboard.
|
||||
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
title: Docker
|
||||
description: Docker extension API
|
||||
keywords: Docker, extensions, sdk, API
|
||||
---
|
||||
|
||||
## Docker objects
|
||||
|
||||
▸ **listContainers**(`options?`): `Promise`<`unknown`\>
|
||||
|
||||
To get the list of containers:
|
||||
|
||||
```typescript
|
||||
const containers = await ddClient.docker.listContainers();
|
||||
```
|
||||
|
||||
▸ **listImages**(`options?`): `Promise`<`unknown`\>
|
||||
|
||||
To get the list of local container images:
|
||||
|
||||
```typescript
|
||||
const images = await ddClient.docker.listImages();
|
||||
```
|
||||
|
||||
See the [Docker API reference](reference/interfaces/Docker.md) for details about these methods.
|
||||
|
||||
> Deprecated access to Docker objects
|
||||
>
|
||||
> The methods below are deprecated and will be removed in a future version. Use the methods specified above.
|
||||
|
||||
```typescript
|
||||
const containers = await window.ddClient.listContainers();
|
||||
|
||||
const images = await window.ddClient.listImages();
|
||||
```
|
||||
|
||||
## Docker commands
|
||||
|
||||
Extensions can also directly execute the `docker` command line.
|
||||
|
||||
▸ **exec**(`cmd`, `args`): `Promise`<[`ExecResult`](reference/interfaces/ExecResult.md)\>
|
||||
|
||||
```typescript
|
||||
const result = await ddClient.docker.cli.exec("info", [
|
||||
"--format",
|
||||
{% raw %}'"{{ json . }}"',{% endraw %}
|
||||
]);
|
||||
```
|
||||
|
||||
The result contains both the standard output and the standard error of the executed command:
|
||||
|
||||
```json
|
||||
{
|
||||
"stderr": "...",
|
||||
"stdout": "..."
|
||||
}
|
||||
```
|
||||
|
||||
In this example, the docker command output is a json output.
|
||||
For convenience, the command result object also has methods to easily parse it:
|
||||
|
||||
- `result.lines(): string[]` splits output lines.
|
||||
- `result.parseJsonObject(): any` parses a well-formed json output.
|
||||
- `result.parseJsonLines(): any[]` parses each output line as a json object.
|
||||
|
||||
▸ **exec**(`cmd`, `args`, `options`): `void`
|
||||
|
||||
The command above streams the output as a result of the execution of a docker command.
|
||||
This is useful if you need to get the output as a stream or the output of the command is too long.
|
||||
|
||||
```typescript
|
||||
await ddClient.docker.cli.exec("logs", ["-f", "..."], {
|
||||
stream: {
|
||||
onOutput(data) {
|
||||
if (data.stdout) {
|
||||
console.error(data.stdout);
|
||||
} else {
|
||||
console.log(data.stderr);
|
||||
}
|
||||
},
|
||||
onError(error) {
|
||||
console.error(error);
|
||||
},
|
||||
onClose(exitCode) {
|
||||
console.log("onClose with exit code " + exitCode);
|
||||
},
|
||||
splitOutputLines: true,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
The child process created by the extension is killed (`SIGTERM`) automatically when you close the dashboard in Docker Desktop or when you exit the extension UI.
|
||||
If needed, you can also use the result of the `exec(streamOptions)` call in order to kill (`SIGTERM`) the process.
|
||||
|
||||
```typescript
|
||||
const logListener = await ddClient.docker.cli.exec("logs", ["-f", "..."], {
|
||||
stream: {
|
||||
// ...
|
||||
},
|
||||
});
|
||||
|
||||
// when done listening to logs or before starting a new one, kill the process
|
||||
logListener.close();
|
||||
```
|
||||
|
||||
This `exec(streamOptions)` API can also be used to listen to docker events:
|
||||
|
||||
```typescript
|
||||
await ddClient.docker.cli.exec(
|
||||
"events",
|
||||
{% raw %}["--format", "{{ json . }}", "--filter", "container=my-container"],{% endraw %}
|
||||
{
|
||||
stream: {
|
||||
onOutput(data) {
|
||||
if (data.stdout) {
|
||||
const event = JSON.parse(data.stdout);
|
||||
console.log(event);
|
||||
} else {
|
||||
console.log(data.stderr);
|
||||
}
|
||||
},
|
||||
onClose(exitCode) {
|
||||
console.log("onClose with exit code " + exitCode);
|
||||
},
|
||||
splitOutputLines: true,
|
||||
},
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
See the [Exec API reference](reference/interfaces/Exec.md) for details about these methods.
|
||||
|
||||
> Deprecated execution of Docker commands
|
||||
>
|
||||
> This method is deprecated and will be removed in a future version. Use the one specified just below.
|
||||
|
||||
```typescript
|
||||
const output = await window.ddClient.execDockerCmd(
|
||||
"info",
|
||||
"--format",
|
||||
{% raw %}'"{{ json . }}"'{% endraw %}
|
||||
);
|
||||
|
||||
window.ddClient.spawnDockerCmd("logs", ["-f", "..."], (data, error) => {
|
||||
console.log(data.stdout);
|
||||
});
|
||||
```
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
title: Extension UI API
|
||||
description: Docker extension development overview
|
||||
keywords: Docker, extensions, sdk, development
|
||||
---
|
||||
|
||||
The extensions UI runs in a sandboxed environment and doesn't have access to any
|
||||
electron or nodejs APIs.
|
||||
|
||||
The extension UI API provides a way for the frontend to perform different actions
|
||||
and communicate with the Docker Desktop dashboard or the underlying system.
|
||||
|
||||
JavaScript API libraries, with Typescript support, are available in order to get all the API definitions in to your extension code.
|
||||
|
||||
- [@docker/extension-api-client](https://www.npmjs.com/package/@docker/extension-api-client) gives access to the extension API entrypoint `DockerDesktopCLient`.
|
||||
- [@docker/extension-api-client-types](https://www.npmjs.com/package/@docker/extension-api-client-types) can be added as a dev dependency in order to get types auto-completion in your IDE.
|
||||
|
||||
```Typescript
|
||||
import { createDockerDesktopClient } from '@docker/extension-api-client';
|
||||
|
||||
export function App() {
|
||||
// obtain Docker Desktop client
|
||||
const ddClient = createDockerDesktopClient();
|
||||
// use ddClient to perform extension actions
|
||||
}
|
||||
```
|
||||
|
||||
The `ddClient` object gives access to various APIs:
|
||||
|
||||
- [Extension Backend](./backend.md)
|
||||
- [Docker](./docker.md)
|
||||
- [Dashboard](./dashboard.md)
|
||||
- [Navigation](./dashboard-routes-navigation.md)
|
||||
|
||||
Find the Extensions API reference [here](./reference/README.md).
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Dashboard Interfaces
|
||||
|
||||
- [Host](interfaces/Host.md)
|
||||
- [NavigationIntents](interfaces/NavigationIntents.md)
|
||||
- [Toast](interfaces/Toast.md)
|
||||
|
||||
### Other Interfaces
|
||||
|
||||
- [ExecResultV0](interfaces/ExecResultV0.md)
|
||||
- [RequestConfigV0](interfaces/RequestConfigV0.md)
|
||||
- [BackendV0](interfaces/BackendV0.md)
|
||||
- [OpenDialogResult](interfaces/OpenDialogResult.md)
|
||||
- [Dialog](interfaces/Dialog.md)
|
||||
- [Docker](interfaces/Docker.md)
|
||||
- [DockerCommand](interfaces/DockerCommand.md)
|
||||
- [Exec](interfaces/Exec.md)
|
||||
- [ExecProcess](interfaces/ExecProcess.md)
|
||||
- [ExecStreamOptions](interfaces/ExecStreamOptions.md)
|
||||
- [ExecResult](interfaces/ExecResult.md)
|
||||
- [RawExecResult](interfaces/RawExecResult.md)
|
||||
- [Extension](interfaces/Extension.md)
|
||||
- [DesktopUI](interfaces/DesktopUI.md)
|
||||
- [ExtensionVM](interfaces/ExtensionVM.md)
|
||||
- [ExtensionHost](interfaces/ExtensionHost.md)
|
||||
- [ExtensionCli](interfaces/ExtensionCli.md)
|
||||
- [HttpService](interfaces/HttpService.md)
|
||||
- [RequestConfig](interfaces/RequestConfig.md)
|
||||
- [DockerDesktopClient](interfaces/DockerDesktopClient.md)
|
||||
|
|
@ -0,0 +1,309 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: BackendV0
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Container Methods
|
||||
|
||||
- [execInContainer](BackendV0.md#execincontainer)
|
||||
|
||||
### HTTP Methods
|
||||
|
||||
- [get](BackendV0.md#get)
|
||||
- [post](BackendV0.md#post)
|
||||
- [put](BackendV0.md#put)
|
||||
- [patch](BackendV0.md#patch)
|
||||
- [delete](BackendV0.md#delete)
|
||||
- [head](BackendV0.md#head)
|
||||
- [request](BackendV0.md#request)
|
||||
|
||||
### VM Methods
|
||||
|
||||
- [execInVMExtension](BackendV0.md#execinvmextension)
|
||||
- [spawnInVMExtension](BackendV0.md#spawninvmextension)
|
||||
|
||||
## Container Methods
|
||||
|
||||
### execInContainer
|
||||
|
||||
▸ **execInContainer**(`container`, `cmd`): `Promise`<[`ExecResultV0`](ExecResultV0.md)\>
|
||||
|
||||
Executes a command inside a container.
|
||||
|
||||
```typescript
|
||||
const output = await window.ddClient.backend.execInContainer(container, cmd);
|
||||
|
||||
console.log(output);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `container` | `string` | - |
|
||||
| `cmd` | `string` | The command to be executed. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<[`ExecResultV0`](ExecResultV0.md)\>
|
||||
|
||||
___
|
||||
|
||||
## HTTP Methods
|
||||
|
||||
### get
|
||||
|
||||
▸ **get**(`url`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP GET request to a backend service.
|
||||
|
||||
```typescript
|
||||
window.ddClient.backend
|
||||
.get("/some/service")
|
||||
.then((value: any) => console.log(value)
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.get](HttpService.md#get) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### post
|
||||
|
||||
▸ **post**(`url`, `data`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP POST request to a backend service.
|
||||
|
||||
```typescript
|
||||
window.ddClient.backend
|
||||
.post("/some/service", { ... })
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.post](HttpService.md#post) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
| `data` | `any` | The body of the request. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### put
|
||||
|
||||
▸ **put**(`url`, `data`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP PUT request to a backend service.
|
||||
|
||||
```typescript
|
||||
window.ddClient.backend
|
||||
.put("/some/service", { ... })
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.put](HttpService.md#put) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
| `data` | `any` | The body of the request. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### patch
|
||||
|
||||
▸ **patch**(`url`, `data`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP PATCH request to a backend service.
|
||||
|
||||
```typescript
|
||||
window.ddClient.backend
|
||||
.patch("/some/service", { ... })
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.patch](HttpService.md#patch) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
| `data` | `any` | The body of the request. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### delete
|
||||
|
||||
▸ **delete**(`url`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP DELETE request to a backend service.
|
||||
|
||||
```typescript
|
||||
window.ddClient.backend
|
||||
.delete("/some/service")
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.delete](HttpService.md#delete) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### head
|
||||
|
||||
▸ **head**(`url`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP HEAD request to a backend service.
|
||||
|
||||
```typescript
|
||||
window.ddClient.backend
|
||||
.head("/some/service")
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.head](HttpService.md#head) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### request
|
||||
|
||||
▸ **request**(`config`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP request to a backend service.
|
||||
|
||||
```typescript
|
||||
window.ddClient.backend
|
||||
.request({ url: "/url", method: "GET", headers: { 'header-key': 'header-value' }, data: { ... }})
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.request](HttpService.md#request) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `config` | [`RequestConfigV0`](RequestConfigV0.md) | The URL of the backend service. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
## VM Methods
|
||||
|
||||
### execInVMExtension
|
||||
|
||||
▸ **execInVMExtension**(`cmd`): `Promise`<[`ExecResultV0`](ExecResultV0.md)\>
|
||||
|
||||
Executes a command inside the backend container.
|
||||
If your extensions ships with additional binaries that should be run inside the backend container you can use the `execInVMExtension` function.
|
||||
|
||||
```typescript
|
||||
const output = await window.ddClient.backend.execInVMExtension(
|
||||
`cliShippedInTheVm xxx`
|
||||
);
|
||||
|
||||
console.log(output);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [ExtensionCli.exec](ExtensionCli.md#exec) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `cmd` | `string` | The command to be executed. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<[`ExecResultV0`](ExecResultV0.md)\>
|
||||
|
||||
___
|
||||
|
||||
### spawnInVMExtension
|
||||
|
||||
▸ **spawnInVMExtension**(`cmd`, `args`, `callback`): `void`
|
||||
|
||||
Returns a stream from the command executed in the backend container.
|
||||
|
||||
```typescript
|
||||
window.ddClient.spawnInVMExtension(
|
||||
`cmd`,
|
||||
[`arg1`, `arg2`],
|
||||
(data: any, err: any) => {
|
||||
console.log(data.stdout, data.stderr);
|
||||
// Once the command exits we get the status code
|
||||
if (data.code) {
|
||||
console.log(data.code);
|
||||
}
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use {@link ExtensionCli.spawn} instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `cmd` | `string` | The command to be executed. |
|
||||
| `args` | `string`[] | The arguments of the command to execute. |
|
||||
| `callback` | (`data`: `any`, `error`: `any`) => `void` | The callback function where to listen from the command output data and errors. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: DesktopUI
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [toast](DesktopUI.md#toast)
|
||||
- [dialog](DesktopUI.md#dialog)
|
||||
- [navigate](DesktopUI.md#navigate)
|
||||
|
||||
## Properties
|
||||
|
||||
### toast
|
||||
|
||||
• `Readonly` **toast**: [`Toast`](Toast.md)
|
||||
|
||||
___
|
||||
|
||||
### dialog
|
||||
|
||||
• `Readonly` **dialog**: [`Dialog`](Dialog.md)
|
||||
|
||||
___
|
||||
|
||||
### navigate
|
||||
|
||||
• `Readonly` **navigate**: [`NavigationIntents`](NavigationIntents.md)
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: Dialog
|
||||
|
||||
Allows opening native dialog boxes.
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Methods
|
||||
|
||||
- [showOpenDialog](Dialog.md#showopendialog)
|
||||
|
||||
## Methods
|
||||
|
||||
### showOpenDialog
|
||||
|
||||
▸ **showOpenDialog**(`dialogProperties`): `Promise`<[`OpenDialogResult`](OpenDialogResult.md)\>
|
||||
|
||||
Display a native open dialog, allowing to select a file or a folder.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.dialog.showOpenDialog({properties: ['openFile']});
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `dialogProperties` | `any` | Properties to specify the open dialog behaviour, see https://www.electronjs.org/docs/latest/api/dialog#dialogshowopendialogbrowserwindow-options. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<[`OpenDialogResult`](OpenDialogResult.md)\>
|
||||
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: Docker
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [cli](Docker.md#cli)
|
||||
|
||||
### Methods
|
||||
|
||||
- [listContainers](Docker.md#listcontainers)
|
||||
- [listImages](Docker.md#listimages)
|
||||
|
||||
## Properties
|
||||
|
||||
### cli
|
||||
|
||||
• `Readonly` **cli**: [`DockerCommand`](DockerCommand.md)
|
||||
|
||||
You can also directly execute the docker binary.
|
||||
|
||||
```typescript
|
||||
const output = await ddClient.docker.cli.exec("info", [
|
||||
"--format",
|
||||
{% raw %}'"{{ json . }}"',{% endraw %}
|
||||
]);
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
{
|
||||
"stderr": "...",
|
||||
"stdout": "..."
|
||||
}
|
||||
```
|
||||
|
||||
In this example the docker command output is a json output.
|
||||
For convenience, the command result object also has methods to easily parse it. See [ExecResult](ExecResult.md) instead.
|
||||
|
||||
---
|
||||
|
||||
Streams the output as a result of the execution of a docker command.
|
||||
It is useful when the output of the command is too long, or you need to get the output as a stream.
|
||||
|
||||
```typescript
|
||||
await ddClient.docker.cli.exec("logs", ["-f", "..."], {
|
||||
stream: {
|
||||
onOutput(data): void {
|
||||
// As we can receive both `stdout` and `stderr`, we wrap them in a JSON object
|
||||
JSON.stringify(
|
||||
{
|
||||
stdout: data.stdout,
|
||||
stderr: data.stderr,
|
||||
},
|
||||
null,
|
||||
" "
|
||||
);
|
||||
},
|
||||
onError(error: any): void {
|
||||
console.error(error);
|
||||
},
|
||||
onClose(exitCode: number): void {
|
||||
console.log("onClose with exit code " + exitCode);
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
||||
### listContainers
|
||||
|
||||
▸ **listContainers**(`options?`): `Promise`<`unknown`\>
|
||||
|
||||
Get the list of running containers (same as `docker ps`).
|
||||
|
||||
By default, this will not list stopped containers.
|
||||
You can use the option `{"all": true}` to list all the running and stopped containers.
|
||||
|
||||
```typescript
|
||||
const containers = await ddClient.docker.listContainers();
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `options?` | `any` | (Optional). A JSON like `{ "all": true, "limit": 10, "size": true, "filters": JSON.stringify({ status: ["exited"] }), }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.37/#operation/ContainerList). |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
---
|
||||
|
||||
### listImages
|
||||
|
||||
▸ **listImages**(`options?`): `Promise`<`unknown`\>
|
||||
|
||||
Get the list of local container images
|
||||
|
||||
```typescript
|
||||
const images = await ddClient.docker.listImages();
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `options?` | `any` | (Optional). A JSON like `{ "all": true, "filters": JSON.stringify({ dangling: ["true"] }), "digests": true }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.37/#tag/Image). |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: DockerCommand
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [exec](DockerCommand.md#exec)
|
||||
|
||||
## Properties
|
||||
|
||||
### exec
|
||||
|
||||
• **exec**: [`Exec`](Exec.md)
|
||||
|
|
@ -0,0 +1,717 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: DockerDesktopClient
|
||||
|
||||
When we moved from the v0 to v1 schema, we made sure
|
||||
window.ddClient satisfied both interfaces. This combined type
|
||||
describes the resulting API. We should delete it when we stop providing
|
||||
the v0 API.
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [backend](DockerDesktopClient.md#backend)
|
||||
- [extension](DockerDesktopClient.md#extension)
|
||||
- [desktopUI](DockerDesktopClient.md#desktopui)
|
||||
- [host](DockerDesktopClient.md#host)
|
||||
- [docker](DockerDesktopClient.md#docker)
|
||||
|
||||
### Container Methods
|
||||
|
||||
- [listContainers](DockerDesktopClient.md#listcontainers)
|
||||
|
||||
### Image Methods
|
||||
|
||||
- [listImages](DockerDesktopClient.md#listimages)
|
||||
|
||||
### Navigation Methods
|
||||
|
||||
- [navigateToContainers](DockerDesktopClient.md#navigatetocontainers)
|
||||
- [navigateToContainer](DockerDesktopClient.md#navigatetocontainer)
|
||||
- [navigateToContainerLogs](DockerDesktopClient.md#navigatetocontainerlogs)
|
||||
- [navigateToContainerInspect](DockerDesktopClient.md#navigatetocontainerinspect)
|
||||
- [navigateToContainerStats](DockerDesktopClient.md#navigatetocontainerstats)
|
||||
- [navigateToImages](DockerDesktopClient.md#navigatetoimages)
|
||||
- [navigateToImage](DockerDesktopClient.md#navigatetoimage)
|
||||
- [navigateToVolumes](DockerDesktopClient.md#navigatetovolumes)
|
||||
- [navigateToVolume](DockerDesktopClient.md#navigatetovolume)
|
||||
- [navigateToDevEnvironments](DockerDesktopClient.md#navigatetodevenvironments)
|
||||
|
||||
### Other Methods
|
||||
|
||||
- [execHostCmd](DockerDesktopClient.md#exechostcmd)
|
||||
- [spawnHostCmd](DockerDesktopClient.md#spawnhostcmd)
|
||||
- [execDockerCmd](DockerDesktopClient.md#execdockercmd)
|
||||
- [spawnDockerCmd](DockerDesktopClient.md#spawndockercmd)
|
||||
- [openExternal](DockerDesktopClient.md#openexternal)
|
||||
|
||||
### Toast Methods
|
||||
|
||||
- [toastSuccess](DockerDesktopClient.md#toastsuccess)
|
||||
- [toastWarning](DockerDesktopClient.md#toastwarning)
|
||||
- [toastError](DockerDesktopClient.md#toasterror)
|
||||
|
||||
## Properties
|
||||
|
||||
### backend
|
||||
|
||||
• `Readonly` **backend**: `undefined` \| [`BackendV0`](BackendV0.md)
|
||||
|
||||
The `window.ddClient.backend` object can be used to communicate with the backend defined in the vm section of
|
||||
the extension metadata.
|
||||
The client is already connected to the backend.
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [DockerDesktopClient.extension](DockerDesktopClient.md#extension) instead.
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.backend
|
||||
|
||||
---
|
||||
|
||||
### extension
|
||||
|
||||
• `Readonly` **extension**: [`Extension`](Extension.md)
|
||||
|
||||
The `ddClient.extension` object can be used to communicate with the backend defined in the vm section of the
|
||||
extension metadata.
|
||||
The client is already connected to the backend.
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV1.extension
|
||||
|
||||
---
|
||||
|
||||
### desktopUI
|
||||
|
||||
• `Readonly` **desktopUI**: [`DesktopUI`](DesktopUI.md)
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV1.desktopUI
|
||||
|
||||
---
|
||||
|
||||
### host
|
||||
|
||||
• `Readonly` **host**: [`Host`](Host.md)
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV1.host
|
||||
|
||||
---
|
||||
|
||||
### docker
|
||||
|
||||
• `Readonly` **docker**: [`Docker`](Docker.md)
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV1.docker
|
||||
|
||||
## Container Methods
|
||||
|
||||
### listContainers
|
||||
|
||||
▸ **listContainers**(`options`): `Promise`<`unknown`\>
|
||||
|
||||
Get the list of running containers (same as `docker ps`).
|
||||
|
||||
By default, this will not list stopped containers.
|
||||
You can use the option `{"all": true}` to list all the running and stopped containers.
|
||||
|
||||
```typescript
|
||||
const containers = await window.ddClient.listContainers();
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [Docker.listContainers](Docker.md#listcontainers) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `options` | `never` | (Optional). A JSON like `{ "all": true, "limit": 10, "size": true, "filters": JSON.stringify({ status: ["exited"] }), }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.37/#operation/ContainerList). |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.listContainers
|
||||
|
||||
---
|
||||
|
||||
## Image Methods
|
||||
|
||||
### listImages
|
||||
|
||||
▸ **listImages**(`options`): `Promise`<`unknown`\>
|
||||
|
||||
Get the list of images
|
||||
|
||||
```typescript
|
||||
const images = await window.ddClient.listImages();
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [Docker.listImages](Docker.md#listimages) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `options` | `never` | (Optional). A JSON like `{ "all": true, "filters": JSON.stringify({ dangling: ["true"] }), "digests": true }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.37/#tag/Image). |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.listImages
|
||||
|
||||
---
|
||||
|
||||
## Navigation Methods
|
||||
|
||||
### navigateToContainers
|
||||
|
||||
▸ **navigateToContainers**(): `void`
|
||||
|
||||
Navigate to the containers window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
window.ddClient.navigateToContainers();
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewContainers](NavigationIntents.md#viewcontainers) instead.
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToContainers
|
||||
|
||||
---
|
||||
|
||||
### navigateToContainer
|
||||
|
||||
▸ **navigateToContainer**(`id`): `Promise`<`any`\>
|
||||
|
||||
Navigate to the container window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await window.ddClient.navigateToContainer(id);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewContainer](NavigationIntents.md#viewcontainer) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`any`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToContainer
|
||||
|
||||
---
|
||||
|
||||
### navigateToContainerLogs
|
||||
|
||||
▸ **navigateToContainerLogs**(`id`): `Promise`<`any`\>
|
||||
|
||||
Navigate to the container logs window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await window.ddClient.navigateToContainerLogs(id);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use {@link DockerDesktopClient.viewContainerLogs} instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`any`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToContainerLogs
|
||||
|
||||
---
|
||||
|
||||
### navigateToContainerInspect
|
||||
|
||||
▸ **navigateToContainerInspect**(`id`): `Promise`<`any`\>
|
||||
|
||||
Navigate to the container inspect window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await window.ddClient.navigateToContainerInspect(id);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use {@link DockerDesktopClient.viewContainerInspect} instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`any`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToContainerInspect
|
||||
|
||||
---
|
||||
|
||||
### navigateToContainerStats
|
||||
|
||||
▸ **navigateToContainerStats**(`id`): `Promise`<`any`\>
|
||||
|
||||
Navigate to the container stats to see the CPU, memory, disk read/write and network I/O usage.
|
||||
|
||||
```typescript
|
||||
await window.ddClient.navigateToContainerStats(id);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use {@link DockerDesktopClient.viewContainerStats} instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`any`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToContainerStats
|
||||
|
||||
---
|
||||
|
||||
### navigateToImages
|
||||
|
||||
▸ **navigateToImages**(): `void`
|
||||
|
||||
Navigate to the images window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await window.ddClient.navigateToImages(id);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewImages](NavigationIntents.md#viewimages) instead.
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToImages
|
||||
|
||||
---
|
||||
|
||||
### navigateToImage
|
||||
|
||||
▸ **navigateToImage**(`id`, `tag`): `Promise`<`any`\>
|
||||
|
||||
Navigate to a specific image referenced by `id` and `tag` in Docker Desktop.
|
||||
In this navigation route you can find the image layers, commands, created time and size.
|
||||
|
||||
```typescript
|
||||
await window.ddClient.navigateToImage(id, tag);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewImage](NavigationIntents.md#viewimage) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :---- | :------- | :----------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | `string` | The full image id (including sha), e.g. `sha256:34ab3ae068572f4e85c448b4035e6be5e19cc41f69606535cd4d768a63432673`. |
|
||||
| `tag` | `string` | The tag of the image, e.g. `latest`, `0.0.1`, etc. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`any`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToImage
|
||||
|
||||
---
|
||||
|
||||
### navigateToVolumes
|
||||
|
||||
▸ **navigateToVolumes**(): `void`
|
||||
|
||||
Navigate to the volumes window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await window.ddClient.navigateToVolumes();
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewVolumes](NavigationIntents.md#viewvolumes) instead.
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToVolumes
|
||||
|
||||
---
|
||||
|
||||
### navigateToVolume
|
||||
|
||||
▸ **navigateToVolume**(`volume`): `void`
|
||||
|
||||
Navigate to a specific volume in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
window.ddClient.navigateToVolume(volume);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewVolume](NavigationIntents.md#viewvolume) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------- | :------- | :---------------------------------------- |
|
||||
| `volume` | `string` | The name of the volume, e.g. `my-volume`. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToVolume
|
||||
|
||||
---
|
||||
|
||||
### navigateToDevEnvironments
|
||||
|
||||
▸ **navigateToDevEnvironments**(): `void`
|
||||
|
||||
Navigate to the Dev Environments window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
window.ddClient.navigateToDevEnvironments();
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewDevEnvironments](NavigationIntents.md#viewdevenvironments) instead.
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.navigateToDevEnvironments
|
||||
|
||||
---
|
||||
|
||||
## Other Methods
|
||||
|
||||
### execHostCmd
|
||||
|
||||
▸ **execHostCmd**(`cmd`): `Promise`<[`ExecResultV0`](ExecResultV0.md)\>
|
||||
|
||||
You can run binaries defined in the host section in the extension metadata.
|
||||
|
||||
```typescript
|
||||
window.ddClient.execHostCmd(`cliShippedOnHost xxx`).then((cmdResult: any) => {
|
||||
console.log(cmdResult);
|
||||
});
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [ExtensionCli.exec](ExtensionCli.md#exec) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :---- | :------- | :-------------------------- |
|
||||
| `cmd` | `string` | The command to be executed. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<[`ExecResultV0`](ExecResultV0.md)\>
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.execHostCmd
|
||||
|
||||
---
|
||||
|
||||
### spawnHostCmd
|
||||
|
||||
▸ **spawnHostCmd**(`cmd`, `args`, `callback`): `void`
|
||||
|
||||
Invoke an extension binary on your host and getting the output stream.
|
||||
|
||||
```typescript
|
||||
window.ddClient.spawnHostCmd(
|
||||
`cliShippedOnHost`,
|
||||
[`arg1`, `arg2`],
|
||||
(data: any, err: any) => {
|
||||
console.log(data.stdout, data.stderr);
|
||||
// Once the command exits we get the status code
|
||||
if (data.code) {
|
||||
console.log(data.code);
|
||||
}
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [ExtensionCli.exec](ExtensionCli.md#exec) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :---------------------------------------- | :----------------------------------------------------------------------------- |
|
||||
| `cmd` | `string` | The command to be executed. |
|
||||
| `args` | `string`[] | The arguments of the command to execute. |
|
||||
| `callback` | (`data`: `any`, `error`: `any`) => `void` | The callback function where to listen from the command output data and errors. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.spawnHostCmd
|
||||
|
||||
---
|
||||
|
||||
### execDockerCmd
|
||||
|
||||
▸ **execDockerCmd**(`cmd`, ...`args`): `Promise`<[`ExecResultV0`](ExecResultV0.md)\>
|
||||
|
||||
You can also directly execute the docker binary.
|
||||
|
||||
```typescript
|
||||
const output = await window.ddClient.execDockerCmd(
|
||||
"info",
|
||||
"--format",
|
||||
{% raw %}'"{{ json . }}"'{% endraw %}
|
||||
);
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [DockerCommand.exec](DockerCommand.md#exec) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :-------- | :--------- | :--------------------------------------- |
|
||||
| `cmd` | `string` | The command to execute. |
|
||||
| `...args` | `string`[] | The arguments of the command to execute. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<[`ExecResultV0`](ExecResultV0.md)\>
|
||||
|
||||
The result will contain both the standard output and the standard error of the executed command:
|
||||
|
||||
```
|
||||
{
|
||||
"stderr": "...",
|
||||
"stdout": "..."
|
||||
}
|
||||
```
|
||||
|
||||
In this example the docker command output is a json output.
|
||||
|
||||
For convenience, the command result object also has methods to easily parse it:
|
||||
|
||||
- `output.lines(): string[]` splits output lines.
|
||||
- `output.parseJsonObject(): any` parses a well-formed json output.
|
||||
- `output.parseJsonLines(): any[]` parses each output line as a json object.
|
||||
|
||||
If the output of the command is too long, or you need to get the output as a stream you can use the
|
||||
spawnDockerCmd function:
|
||||
|
||||
```typescript
|
||||
window.ddClient.spawnDockerCmd("logs", ["-f", "..."], (data, error) => {
|
||||
console.log(data.stdout);
|
||||
});
|
||||
```
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.execDockerCmd
|
||||
|
||||
---
|
||||
|
||||
### spawnDockerCmd
|
||||
|
||||
▸ **spawnDockerCmd**(`cmd`, `args`, `callback`): `void`
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [DockerCommand.exec](DockerCommand.md#exec) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :---------------------------------------- |
|
||||
| `cmd` | `string` |
|
||||
| `args` | `string`[] |
|
||||
| `callback` | (`data`: `any`, `error`: `any`) => `void` |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.spawnDockerCmd
|
||||
|
||||
---
|
||||
|
||||
### openExternal
|
||||
|
||||
▸ **openExternal**(`url`): `void`
|
||||
|
||||
Opens an external URL with the system default browser.
|
||||
|
||||
```typescript
|
||||
window.ddClient.openExternal("https://docker.com");
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [Host.openExternal](Host.md#openexternal) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :---- | :------- | :------------------------------------------------------------------------ |
|
||||
| `url` | `string` | The URL the browser will open (must have the protocol `http` or `https`). |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.openExternal
|
||||
|
||||
---
|
||||
|
||||
## Toast Methods
|
||||
|
||||
### toastSuccess
|
||||
|
||||
▸ **toastSuccess**(`msg`): `void`
|
||||
|
||||
Display a toast message of type success.
|
||||
|
||||
```typescript
|
||||
window.ddClient.toastSuccess("message");
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [Toast.success](Toast.md#success) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :---- | :------- | :----------------------------------- |
|
||||
| `msg` | `string` | The message to display in the toast. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.toastSuccess
|
||||
|
||||
---
|
||||
|
||||
### toastWarning
|
||||
|
||||
▸ **toastWarning**(`msg`): `void`
|
||||
|
||||
Display a toast message of type warning.
|
||||
|
||||
```typescript
|
||||
window.ddClient.toastWarning("message");
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [Toast.warning](Toast.md#warning) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :---- | :------- | :----------------------------------- |
|
||||
| `msg` | `string` | The message to display in the toast. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.toastWarning
|
||||
|
||||
---
|
||||
|
||||
### toastError
|
||||
|
||||
▸ **toastError**(`msg`): `void`
|
||||
|
||||
Display a toast message of type error.
|
||||
|
||||
```typescript
|
||||
window.ddClient.toastError("message");
|
||||
```
|
||||
|
||||
**`deprecated`** :warning: It will be removed in a future version. Use [Toast.error](Toast.md#error) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :---- | :------- | :----------------------------------- |
|
||||
| `msg` | `string` | The message to display in the toast. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
DockerDesktopClientV0.toastError
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: Exec
|
||||
|
||||
## Callable
|
||||
|
||||
### Exec
|
||||
|
||||
▸ **Exec**(`cmd`, `args`): `Promise`<[`ExecResult`](ExecResult.md)\>
|
||||
|
||||
Executes a command.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `cmd` | `string` | The command to execute. |
|
||||
| `args` | `string`[] | The arguments of the command to execute. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<[`ExecResult`](ExecResult.md)\>
|
||||
|
||||
A promise that will resolve once the command finishes.
|
||||
|
||||
### Exec
|
||||
|
||||
▸ **Exec**(`cmd`, `args`, `options`): [`ExecProcess`](ExecProcess.md)
|
||||
|
||||
Streams the result of a command if `stream` is specified in the `options` parameter.
|
||||
|
||||
Specify the `stream` if the output of your command is too long or if you need to stream things indefinitely (for example container logs).
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `cmd` | `string` | The command to execute. |
|
||||
| `args` | `string`[] | The arguments of the command to execute. |
|
||||
| `options` | `Object` | The list of options. |
|
||||
| `options.stream` | [`ExecStreamOptions`](ExecStreamOptions.md) | Provides three functions: `onOutput` (invoked every time `stdout` or `stderr` is received), `onError` and `onClose` (invoked when the stream has ended). |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`ExecProcess`](ExecProcess.md)
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: ExecProcess
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Methods
|
||||
|
||||
- [close](ExecProcess.md#close)
|
||||
|
||||
## Methods
|
||||
|
||||
### close
|
||||
|
||||
▸ **close**(): `void`
|
||||
|
||||
Close the process started by exec(streamingOptions)
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
|
@ -0,0 +1,132 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: ExecResult
|
||||
|
||||
## Hierarchy
|
||||
|
||||
- [`RawExecResult`](RawExecResult.md)
|
||||
|
||||
↳ **`ExecResult`**
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Methods
|
||||
|
||||
- [lines](ExecResult.md#lines)
|
||||
- [parseJsonLines](ExecResult.md#parsejsonlines)
|
||||
- [parseJsonObject](ExecResult.md#parsejsonobject)
|
||||
|
||||
### Properties
|
||||
|
||||
- [cmd](ExecResult.md#cmd)
|
||||
- [killed](ExecResult.md#killed)
|
||||
- [signal](ExecResult.md#signal)
|
||||
- [code](ExecResult.md#code)
|
||||
- [stdout](ExecResult.md#stdout)
|
||||
- [stderr](ExecResult.md#stderr)
|
||||
|
||||
## Methods
|
||||
|
||||
### lines
|
||||
|
||||
▸ **lines**(): `string`[]
|
||||
|
||||
Split output lines.
|
||||
|
||||
#### Returns
|
||||
|
||||
`string`[]
|
||||
|
||||
The list of lines.
|
||||
|
||||
___
|
||||
|
||||
### parseJsonLines
|
||||
|
||||
▸ **parseJsonLines**(): `any`[]
|
||||
|
||||
Parse each output line as a JSON object.
|
||||
|
||||
#### Returns
|
||||
|
||||
`any`[]
|
||||
|
||||
The list of lines where each line is a JSON object.
|
||||
|
||||
___
|
||||
|
||||
### parseJsonObject
|
||||
|
||||
▸ **parseJsonObject**(): `any`
|
||||
|
||||
Parse a well-formed JSON output.
|
||||
|
||||
#### Returns
|
||||
|
||||
`any`
|
||||
|
||||
The JSON object.
|
||||
|
||||
## Properties
|
||||
|
||||
### cmd
|
||||
|
||||
• `Optional` `Readonly` **cmd**: `string`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
[RawExecResult](RawExecResult.md).[cmd](RawExecResult.md#cmd)
|
||||
|
||||
___
|
||||
|
||||
### killed
|
||||
|
||||
• `Optional` `Readonly` **killed**: `boolean`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
[RawExecResult](RawExecResult.md).[killed](RawExecResult.md#killed)
|
||||
|
||||
___
|
||||
|
||||
### signal
|
||||
|
||||
• `Optional` `Readonly` **signal**: `string`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
[RawExecResult](RawExecResult.md).[signal](RawExecResult.md#signal)
|
||||
|
||||
___
|
||||
|
||||
### code
|
||||
|
||||
• `Optional` `Readonly` **code**: `number`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
[RawExecResult](RawExecResult.md).[code](RawExecResult.md#code)
|
||||
|
||||
___
|
||||
|
||||
### stdout
|
||||
|
||||
• `Readonly` **stdout**: `string`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
[RawExecResult](RawExecResult.md).[stdout](RawExecResult.md#stdout)
|
||||
|
||||
___
|
||||
|
||||
### stderr
|
||||
|
||||
• `Readonly` **stderr**: `string`
|
||||
|
||||
#### Inherited from
|
||||
|
||||
[RawExecResult](RawExecResult.md).[stderr](RawExecResult.md#stderr)
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: ExecResultV0
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [cmd](ExecResultV0.md#cmd)
|
||||
- [killed](ExecResultV0.md#killed)
|
||||
- [signal](ExecResultV0.md#signal)
|
||||
- [code](ExecResultV0.md#code)
|
||||
- [stdout](ExecResultV0.md#stdout)
|
||||
- [stderr](ExecResultV0.md#stderr)
|
||||
|
||||
### Methods
|
||||
|
||||
- [lines](ExecResultV0.md#lines)
|
||||
- [parseJsonLines](ExecResultV0.md#parsejsonlines)
|
||||
- [parseJsonObject](ExecResultV0.md#parsejsonobject)
|
||||
|
||||
## Properties
|
||||
|
||||
### cmd
|
||||
|
||||
• `Optional` `Readonly` **cmd**: `string`
|
||||
|
||||
___
|
||||
|
||||
### killed
|
||||
|
||||
• `Optional` `Readonly` **killed**: `boolean`
|
||||
|
||||
___
|
||||
|
||||
### signal
|
||||
|
||||
• `Optional` `Readonly` **signal**: `string`
|
||||
|
||||
___
|
||||
|
||||
### code
|
||||
|
||||
• `Optional` `Readonly` **code**: `number`
|
||||
|
||||
___
|
||||
|
||||
### stdout
|
||||
|
||||
• `Readonly` **stdout**: `string`
|
||||
|
||||
___
|
||||
|
||||
### stderr
|
||||
|
||||
• `Readonly` **stderr**: `string`
|
||||
|
||||
## Methods
|
||||
|
||||
### lines
|
||||
|
||||
▸ **lines**(): `string`[]
|
||||
|
||||
Split output lines.
|
||||
|
||||
#### Returns
|
||||
|
||||
`string`[]
|
||||
|
||||
The list of lines.
|
||||
|
||||
___
|
||||
|
||||
### parseJsonLines
|
||||
|
||||
▸ **parseJsonLines**(): `any`[]
|
||||
|
||||
Parse each output line as a JSON object.
|
||||
|
||||
#### Returns
|
||||
|
||||
`any`[]
|
||||
|
||||
The list of lines where each line is a JSON object.
|
||||
|
||||
___
|
||||
|
||||
### parseJsonObject
|
||||
|
||||
▸ **parseJsonObject**(): `any`
|
||||
|
||||
Parse a well-formed JSON output.
|
||||
|
||||
#### Returns
|
||||
|
||||
`any`
|
||||
|
||||
The JSON object.
|
||||
|
|
@ -0,0 +1,84 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: ExecStreamOptions
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Methods
|
||||
|
||||
- [onOutput](ExecStreamOptions.md#onoutput)
|
||||
- [onError](ExecStreamOptions.md#onerror)
|
||||
- [onClose](ExecStreamOptions.md#onclose)
|
||||
|
||||
### Properties
|
||||
|
||||
- [splitOutputLines](ExecStreamOptions.md#splitoutputlines)
|
||||
|
||||
## Methods
|
||||
|
||||
### onOutput
|
||||
|
||||
▸ `Optional` **onOutput**(`data`): `void`
|
||||
|
||||
Invoked when receiving output from command execution.
|
||||
By default, the output is split into chunks at arbitrary boundaries.
|
||||
If you prefer the output to be split into complete lines, set `splitOutputLines`
|
||||
to true. The callback is then invoked once for each line.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `data` | { `stdout`: `string` ; `stderr?`: `undefined` } \| { `stdout?`: `undefined` ; `stderr`: `string` } | output content. Can include either stdout string, or stderr string, one at a time. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
___
|
||||
|
||||
### onError
|
||||
|
||||
▸ `Optional` **onError**(`error`): `void`
|
||||
|
||||
Invoked to report error if the executed command errors.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `error` | `any` | the error happening in the executed command |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
___
|
||||
|
||||
### onClose
|
||||
|
||||
▸ `Optional` **onClose**(`exitCode`): `void`
|
||||
|
||||
Invoked when process exits.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `exitCode` | `number` | the process exit code |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
## Properties
|
||||
|
||||
### splitOutputLines
|
||||
|
||||
• `Optional` `Readonly` **splitOutputLines**: `boolean`
|
||||
|
||||
Specifies the behaviour invoking `onOutput(data)`. Raw output by default, splitting output at any position. If set to true, `onOutput` will be invoked once for each line.
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: Extension
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [vm](Extension.md#vm)
|
||||
- [host](Extension.md#host)
|
||||
|
||||
## Properties
|
||||
|
||||
### vm
|
||||
|
||||
• `Optional` `Readonly` **vm**: [`ExtensionVM`](ExtensionVM.md)
|
||||
|
||||
___
|
||||
|
||||
### host
|
||||
|
||||
• `Optional` `Readonly` **host**: [`ExtensionHost`](ExtensionHost.md)
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: ExtensionCli
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [exec](ExtensionCli.md#exec)
|
||||
|
||||
## Properties
|
||||
|
||||
### exec
|
||||
|
||||
• **exec**: [`Exec`](Exec.md)
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: ExtensionHost
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [cli](ExtensionHost.md#cli)
|
||||
|
||||
## Properties
|
||||
|
||||
### cli
|
||||
|
||||
• `Readonly` **cli**: [`ExtensionCli`](ExtensionCli.md)
|
||||
|
||||
Executes a command in the host.
|
||||
|
||||
For example, execute the shipped binary `kubectl -h` command in the **host**:
|
||||
|
||||
```typescript
|
||||
await ddClient.extension.host.cli.exec("kubectl", ["-h"]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Streams the output of the command executed in the backend container or in the host.
|
||||
|
||||
Provided the `kubectl` binary is shipped as part of your extension, you can spawn the `kubectl -h` command in the **host**:
|
||||
|
||||
```typescript
|
||||
await ddClient.extension.host.cli.exec("kubectl", ["-h"], {
|
||||
stream: {
|
||||
onOutput(data): void {
|
||||
// As we can receive both `stdout` and `stderr`, we wrap them in a JSON object
|
||||
JSON.stringify(
|
||||
{
|
||||
stdout: data.stdout,
|
||||
stderr: data.stderr,
|
||||
},
|
||||
null,
|
||||
" "
|
||||
);
|
||||
},
|
||||
onError(error: any): void {
|
||||
console.error(error);
|
||||
},
|
||||
onClose(exitCode: number): void {
|
||||
console.log("onClose with exit code " + exitCode);
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: ExtensionVM
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [cli](ExtensionVM.md#cli)
|
||||
- [service](ExtensionVM.md#service)
|
||||
|
||||
## Properties
|
||||
|
||||
### cli
|
||||
|
||||
• `Readonly` **cli**: [`ExtensionCli`](ExtensionCli.md)
|
||||
|
||||
Executes a command in the backend container.
|
||||
|
||||
Example: Execute the command `ls -l` inside the **backend container**:
|
||||
|
||||
```typescript
|
||||
await ddClient.extension.vm.cli.exec("ls", ["-l"]);
|
||||
```
|
||||
|
||||
Streams the output of the command executed in the backend container.
|
||||
|
||||
Example: Spawn the command `ls -l` inside the **backend container**:
|
||||
|
||||
```typescript
|
||||
await ddClient.extension.vm.cli.exec("ls", ["-l"], {
|
||||
stream: {
|
||||
onOutput(data): void {
|
||||
// As we can receive both `stdout` and `stderr`, we wrap them in a JSON object
|
||||
JSON.stringify(
|
||||
{
|
||||
stdout: data.stdout,
|
||||
stderr: data.stderr,
|
||||
},
|
||||
null,
|
||||
" "
|
||||
);
|
||||
},
|
||||
onError(error: any): void {
|
||||
console.error(error);
|
||||
},
|
||||
onClose(exitCode: number): void {
|
||||
console.log("onClose with exit code " + exitCode);
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**`param`** Command to execute.
|
||||
|
||||
**`param`** Arguments of the command to execute.
|
||||
|
||||
**`param`** The callback function where to listen from the command output data and errors.
|
||||
|
||||
---
|
||||
|
||||
### service
|
||||
|
||||
• `Optional` `Readonly` **service**: [`HttpService`](HttpService.md)
|
||||
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: Host
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Methods
|
||||
|
||||
- [openExternal](Host.md#openexternal)
|
||||
|
||||
### Properties
|
||||
|
||||
- [platform](Host.md#platform)
|
||||
- [arch](Host.md#arch)
|
||||
- [hostname](Host.md#hostname)
|
||||
|
||||
## Methods
|
||||
|
||||
### openExternal
|
||||
|
||||
▸ **openExternal**(`url`): `void`
|
||||
|
||||
Opens an external URL with the system default browser.
|
||||
|
||||
```typescript
|
||||
ddClient.host.openExternal("https://docker.com");
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL the browser will open (must have the protocol `http` or `https`). |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
## Properties
|
||||
|
||||
### platform
|
||||
|
||||
• **platform**: `string`
|
||||
|
||||
Returns a string identifying the operating system platform. See https://nodejs.org/api/os.html#osplatform
|
||||
|
||||
___
|
||||
|
||||
### arch
|
||||
|
||||
• **arch**: `string`
|
||||
|
||||
Returns the operating system CPU architecture. See https://nodejs.org/api/os.html#osarch
|
||||
|
||||
___
|
||||
|
||||
### hostname
|
||||
|
||||
• **hostname**: `string`
|
||||
|
||||
Returns the host name of the operating system. See https://nodejs.org/api/os.html#oshostname
|
||||
|
|
@ -0,0 +1,190 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: HttpService
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Methods
|
||||
|
||||
- [get](HttpService.md#get)
|
||||
- [post](HttpService.md#post)
|
||||
- [put](HttpService.md#put)
|
||||
- [patch](HttpService.md#patch)
|
||||
- [delete](HttpService.md#delete)
|
||||
- [head](HttpService.md#head)
|
||||
- [request](HttpService.md#request)
|
||||
|
||||
## Methods
|
||||
|
||||
### get
|
||||
|
||||
▸ **get**(`url`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP GET request to a backend service.
|
||||
|
||||
```typescript
|
||||
ddClient.extension.vm.service
|
||||
.get("/some/service")
|
||||
.then((value: any) => console.log(value)
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### post
|
||||
|
||||
▸ **post**(`url`, `data`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP POST request to a backend service.
|
||||
|
||||
```typescript
|
||||
ddClient.extension.vm.service
|
||||
.post("/some/service", { ... })
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
| `data` | `any` | The body of the request. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### put
|
||||
|
||||
▸ **put**(`url`, `data`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP PUT request to a backend service.
|
||||
|
||||
```typescript
|
||||
ddClient.extension.vm.service
|
||||
.put("/some/service", { ... })
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
| `data` | `any` | The body of the request. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### patch
|
||||
|
||||
▸ **patch**(`url`, `data`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP PATCH request to a backend service.
|
||||
|
||||
```typescript
|
||||
ddClient.extension.vm.service
|
||||
.patch("/some/service", { ... })
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
| `data` | `any` | The body of the request. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### delete
|
||||
|
||||
▸ **delete**(`url`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP DELETE request to a backend service.
|
||||
|
||||
```typescript
|
||||
ddClient.extension.vm.service
|
||||
.delete("/some/service")
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### head
|
||||
|
||||
▸ **head**(`url`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP HEAD request to a backend service.
|
||||
|
||||
```typescript
|
||||
ddClient.extension.vm.service
|
||||
.head("/some/service")
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `url` | `string` | The URL of the backend service. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
||||
___
|
||||
|
||||
### request
|
||||
|
||||
▸ **request**(`config`): `Promise`<`unknown`\>
|
||||
|
||||
Performs an HTTP request to a backend service.
|
||||
|
||||
```typescript
|
||||
ddClient.extension.vm.service
|
||||
.request({ url: "/url", method: "GET", headers: { 'header-key': 'header-value' }, data: { ... }})
|
||||
.then((value: any) => console.log(value));
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `config` | [`RequestConfig`](RequestConfig.md) | The URL of the backend service. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`unknown`\>
|
||||
|
|
@ -0,0 +1,245 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: NavigationIntents
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Container Methods
|
||||
|
||||
- [viewContainers](NavigationIntents.md#viewcontainers)
|
||||
- [viewContainer](NavigationIntents.md#viewcontainer)
|
||||
- [viewContainerLogs](NavigationIntents.md#viewcontainerlogs)
|
||||
- [viewContainerInspect](NavigationIntents.md#viewcontainerinspect)
|
||||
- [viewContainerStats](NavigationIntents.md#viewcontainerstats)
|
||||
|
||||
### Images Methods
|
||||
|
||||
- [viewImages](NavigationIntents.md#viewimages)
|
||||
- [viewImage](NavigationIntents.md#viewimage)
|
||||
|
||||
### Other Methods
|
||||
|
||||
- [viewDevEnvironments](NavigationIntents.md#viewdevenvironments)
|
||||
|
||||
### Volume Methods
|
||||
|
||||
- [viewVolumes](NavigationIntents.md#viewvolumes)
|
||||
- [viewVolume](NavigationIntents.md#viewvolume)
|
||||
|
||||
## Container Methods
|
||||
|
||||
### viewContainers
|
||||
|
||||
▸ **viewContainers**(): `Promise`<`void`\>
|
||||
|
||||
Navigate to the containers window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.navigate.viewContainers()
|
||||
```
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
___
|
||||
|
||||
### viewContainer
|
||||
|
||||
▸ **viewContainer**(`id`): `Promise`<`void`\>
|
||||
|
||||
Navigate to the container window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await ddClient.desktopUI.navigate.viewContainer(id)
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
___
|
||||
|
||||
### viewContainerLogs
|
||||
|
||||
▸ **viewContainerLogs**(`id`): `Promise`<`void`\>
|
||||
|
||||
Navigate to the container logs window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await ddClient.desktopUI.navigate.viewContainerLogs(id)
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
___
|
||||
|
||||
### viewContainerInspect
|
||||
|
||||
▸ **viewContainerInspect**(`id`): `Promise`<`void`\>
|
||||
|
||||
Navigate to the container inspect window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await ddClient.desktopUI.navigate.viewContainerInspect(id)
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
___
|
||||
|
||||
### viewContainerStats
|
||||
|
||||
▸ **viewContainerStats**(`id`): `Promise`<`void`\>
|
||||
|
||||
Navigate to the container stats to see the CPU, memory, disk read/write and network I/O usage.
|
||||
|
||||
```typescript
|
||||
await ddClient.desktopUI.navigate.viewContainerStats(id)
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
A promise that fails if the container doesn't exist.
|
||||
|
||||
___
|
||||
|
||||
## Images Methods
|
||||
|
||||
### viewImages
|
||||
|
||||
▸ **viewImages**(): `Promise`<`void`\>
|
||||
|
||||
Navigate to the images window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await ddClient.desktopUI.navigate.viewImages()
|
||||
```
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
___
|
||||
|
||||
### viewImage
|
||||
|
||||
▸ **viewImage**(`id`, `tag`): `Promise`<`void`\>
|
||||
|
||||
Navigate to a specific image referenced by `id` and `tag` in Docker Desktop.
|
||||
In this navigation route you can find the image layers, commands, created time and size.
|
||||
|
||||
```typescript
|
||||
await ddClient.desktopUI.navigate.viewImage(id, tag)
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `id` | `string` | The full image id (including sha), e.g. `sha256:34ab3ae068572f4e85c448b4035e6be5e19cc41f69606535cd4d768a63432673`. |
|
||||
| `tag` | `string` | The tag of the image, e.g. `latest`, `0.0.1`, etc. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
A promise that fails if the image doesn't exist.
|
||||
|
||||
___
|
||||
|
||||
## Other Methods
|
||||
|
||||
### viewDevEnvironments
|
||||
|
||||
▸ **viewDevEnvironments**(): `Promise`<`void`\>
|
||||
|
||||
Navigate to the Dev Environments window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.navigate.viewDevEnvironments()
|
||||
```
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
___
|
||||
|
||||
## Volume Methods
|
||||
|
||||
### viewVolumes
|
||||
|
||||
▸ **viewVolumes**(): `Promise`<`void`\>
|
||||
|
||||
Navigate to the volumes window in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.navigate.viewVolumes()
|
||||
```
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
||||
___
|
||||
|
||||
### viewVolume
|
||||
|
||||
▸ **viewVolume**(`volume`): `Promise`<`void`\>
|
||||
|
||||
Navigate to a specific volume in Docker Desktop.
|
||||
|
||||
```typescript
|
||||
await ddClient.desktopUI.navigate.viewVolume(volume)
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `volume` | `string` | The name of the volume, e.g. `my-volume`. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Promise`<`void`\>
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: OpenDialogResult
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [canceled](OpenDialogResult.md#canceled)
|
||||
- [filePaths](OpenDialogResult.md#filepaths)
|
||||
- [bookmarks](OpenDialogResult.md#bookmarks)
|
||||
|
||||
## Properties
|
||||
|
||||
### canceled
|
||||
|
||||
• `Readonly` **canceled**: `boolean`
|
||||
|
||||
Whether the dialog was canceled.
|
||||
|
||||
___
|
||||
|
||||
### filePaths
|
||||
|
||||
• `Readonly` **filePaths**: `string`[]
|
||||
|
||||
An array of file paths chosen by the user. If the dialog is cancelled this will be an empty array.
|
||||
|
||||
___
|
||||
|
||||
### bookmarks
|
||||
|
||||
• `Optional` `Readonly` **bookmarks**: `string`[]
|
||||
|
||||
macOS only- An array matching the filePaths array of base64 encoded strings which contains security scoped bookmark data. securityScopedBookmarks must be enabled for this to be populated
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: RawExecResult
|
||||
|
||||
## Hierarchy
|
||||
|
||||
- **`RawExecResult`**
|
||||
|
||||
↳ [`ExecResult`](ExecResult.md)
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [cmd](RawExecResult.md#cmd)
|
||||
- [killed](RawExecResult.md#killed)
|
||||
- [signal](RawExecResult.md#signal)
|
||||
- [code](RawExecResult.md#code)
|
||||
- [stdout](RawExecResult.md#stdout)
|
||||
- [stderr](RawExecResult.md#stderr)
|
||||
|
||||
## Properties
|
||||
|
||||
### cmd
|
||||
|
||||
• `Optional` `Readonly` **cmd**: `string`
|
||||
|
||||
___
|
||||
|
||||
### killed
|
||||
|
||||
• `Optional` `Readonly` **killed**: `boolean`
|
||||
|
||||
___
|
||||
|
||||
### signal
|
||||
|
||||
• `Optional` `Readonly` **signal**: `string`
|
||||
|
||||
___
|
||||
|
||||
### code
|
||||
|
||||
• `Optional` `Readonly` **code**: `number`
|
||||
|
||||
___
|
||||
|
||||
### stdout
|
||||
|
||||
• `Readonly` **stdout**: `string`
|
||||
|
||||
___
|
||||
|
||||
### stderr
|
||||
|
||||
• `Readonly` **stderr**: `string`
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: RequestConfig
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [url](RequestConfig.md#url)
|
||||
- [method](RequestConfig.md#method)
|
||||
- [headers](RequestConfig.md#headers)
|
||||
- [data](RequestConfig.md#data)
|
||||
|
||||
## Properties
|
||||
|
||||
### url
|
||||
|
||||
• `Readonly` **url**: `string`
|
||||
|
||||
___
|
||||
|
||||
### method
|
||||
|
||||
• `Readonly` **method**: `string`
|
||||
|
||||
___
|
||||
|
||||
### headers
|
||||
|
||||
• `Readonly` **headers**: `Record`<`string`, `string`\>
|
||||
|
||||
___
|
||||
|
||||
### data
|
||||
|
||||
• `Readonly` **data**: `any`
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: RequestConfigV0
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [url](RequestConfigV0.md#url)
|
||||
- [method](RequestConfigV0.md#method)
|
||||
- [headers](RequestConfigV0.md#headers)
|
||||
- [data](RequestConfigV0.md#data)
|
||||
|
||||
## Properties
|
||||
|
||||
### url
|
||||
|
||||
• `Readonly` **url**: `string`
|
||||
|
||||
___
|
||||
|
||||
### method
|
||||
|
||||
• `Readonly` **method**: `string`
|
||||
|
||||
___
|
||||
|
||||
### headers
|
||||
|
||||
• `Readonly` **headers**: `Record`<`string`, `string`\>
|
||||
|
||||
___
|
||||
|
||||
### data
|
||||
|
||||
• `Readonly` **data**: `any`
|
||||
|
|
@ -0,0 +1,85 @@
|
|||
---
|
||||
title: Docker extension API reference
|
||||
description: Docker extension API reference
|
||||
keywords: Docker, extensions, sdk, API, reference
|
||||
---
|
||||
|
||||
# Interface: Toast
|
||||
|
||||
Toasts provide a brief notification to the user.
|
||||
They appear temporarily and shouldn't interrupt the user experience.
|
||||
They also don't require user input to disappear.
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Methods
|
||||
|
||||
- [success](Toast.md#success)
|
||||
- [warning](Toast.md#warning)
|
||||
- [error](Toast.md#error)
|
||||
|
||||
## Methods
|
||||
|
||||
### success
|
||||
|
||||
▸ **success**(`msg`): `void`
|
||||
|
||||
Display a toast message of type success.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.toast.success("message");
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `msg` | `string` | The message to display in the toast. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
___
|
||||
|
||||
### warning
|
||||
|
||||
▸ **warning**(`msg`): `void`
|
||||
|
||||
Display a toast message of type warning.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.toast.warning("message");
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `msg` | `string` | The message to display in the warning. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
___
|
||||
|
||||
### error
|
||||
|
||||
▸ **error**(`msg`): `void`
|
||||
|
||||
Display a toast message of type error.
|
||||
|
||||
```typescript
|
||||
ddClient.desktopUI.toast.error("message");
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `msg` | `string` | The message to display in the toast. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
title: Build, test, and install an extension
|
||||
description: Docker extension CLI
|
||||
keywords: Docker, extensions, sdk, cli
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
To build the extension, run:
|
||||
|
||||
```console
|
||||
$ make build-extension
|
||||
# or docker build -t my-extension .
|
||||
```
|
||||
|
||||
To install the extension, run:
|
||||
|
||||
```console
|
||||
$ docker extension install my-extension
|
||||
```
|
||||
|
||||
> Using the CLI to install unpublished extensions
|
||||
>
|
||||
> 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
|
||||
$ 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:
|
||||
|
||||
```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
|
||||
```
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Usage overview
|
||||
description: Docker extension CLI
|
||||
keywords: Docker, extensions, sdk, CLI
|
||||
---
|
||||
|
||||
The Extensions CLI is an extension development tool that is used to manage Docker extensions. Actions include install, list, remove, and validate extensions.
|
||||
|
||||
- `docker extension enable` enables Docker extensions.
|
||||
- `docker extension dev` commands for extension development.
|
||||
- `docker extension disable` disables Docker extensions.
|
||||
- `docker extension init` creates a new Docker extension.
|
||||
- `docker extension install ` installs a Docker Extension with the specified image.
|
||||
- `docker extension ls` list installed Docker extensions.
|
||||
- `docker extension rm` removes a Docker extension.
|
||||
- `docker extension update` removes and re-installs a Docker extension.
|
||||
- `docker extension validate` validates the extension metadata file against the JSON schema.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 297 KiB |
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
title: OAuth 2.0 flow
|
||||
description: Docker extension OAuth 2.0 flow
|
||||
keywords: Docker, extensions, sdk, OAuth 2.0
|
||||
---
|
||||
|
||||
You may need users to authenticate from your Docker Extension using OAuth 2.0 via the web browser, and return them back into the Docker Extension.
|
||||
|
||||
> ** Note **
|
||||
>
|
||||
> This page assumes that you already have an identity provider (IdP) which handles the authentication process and returns an access token, like Google, Azure AD or Okta, among many others.
|
||||
|
||||
## Introduction
|
||||
|
||||
In OAuth 2.0, the term "grant type" refers to the way an application gets an access token. Although OAuth 2.0 defines several grant types, this page will only describe how to authorize users from your Docker Extension using the Authorization Code grant type.
|
||||
|
||||
## Authorization Code Grant Flow
|
||||
|
||||
The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token.
|
||||
|
||||
After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token.
|
||||
|
||||
{: style=width:80% }
|
||||
|
||||
- The Docker Extension makes a request for the user to authorize access to their data.
|
||||
- If the user grants access, the Docker Extension then requests an access token from the service provider, passing the access grant from the user and - authentication details to identify the client.
|
||||
- The service provider validates these details and returns an access token.
|
||||
- The Docker Extension uses the access token to request the user data with the service provider.
|
||||
|
||||
## OAuth 2.0 terminology
|
||||
|
||||
- **Auth URL** - The endpoint for the API provider authorization server, to retrieve the auth code.
|
||||
- **Redirect URI** - The client application callback URL to redirect to after auth. This must be registered with the API provider.
|
||||
|
||||
Once the user enters the username and password, he would have been successfully authenticated.
|
||||
|
||||
## Open a browser page to authenticate the user
|
||||
|
||||
From the extension UI, you can provide a button that, on click, it opens a browser window 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 instance:
|
||||
|
||||
```typescript
|
||||
window.ddClient.openExternal("https://authorization-server.com/authorize?
|
||||
response_type=code
|
||||
&client_id=T70hJ3ls5VTYG8ylX3CZsfIu
|
||||
&redirect_uri=${REDIRECT_URI}
|
||||
&scope=photo+offline_access
|
||||
&state=kH_0FdAtjCfYjOkF);
|
||||
```
|
||||
|
||||
## Get the authorization code and access token
|
||||
|
||||
### From the extension UI
|
||||
|
||||
> **Passing the access token**
|
||||
>
|
||||
> At the moment of this writing, passing the authorization code as a query parameter to the `docker-desktop://dashboard/open` URL is not supported.
|
||||
> {: .warning}
|
||||
|
||||
You will not be able to get the authorization code from the extension UI by listing `docker-desktop://dashboard/open` as the `redirect_uri` in the OAuth app you're using and concatenating the authorization code as a query parameter.
|
||||
|
||||
See [from backend service](#from-a-backend-service) instead.
|
||||
|
||||
### From a backend service
|
||||
|
||||
You will need a backend service running as part of your extension that handles the OAuth 2.0 flow. For this, you must ensure the Redirect URI has been registered with the API provider to redirect to that location after OAuth had completed, e.g. `http://localhost:8080/callback`.
|
||||
|
||||
The default communication is socket-based, so the backend service will actually need to expose the port in order for the browser to connect to it.
|
||||
|
||||
#### Authorization
|
||||
|
||||
This is the step where the user enters its credentials in the browser. After the authorization is completed successfully, the user will be redirected back to your backend service, and you'll consume the authorization code that is part of the query parameters in the URL.
|
||||
|
||||
How you will consume the query parameters will depend on the technology that is used by the backend service.
|
||||
|
||||
#### Exchange the Authorization Code
|
||||
|
||||
Now you're ready to exchange the authorization code for an access token.
|
||||
|
||||
The backend service must build a `POST` request to the token endpoint with the following parameters, for instance:
|
||||
|
||||
```
|
||||
POST https://authorization-server.com/token
|
||||
|
||||
grant_type=authorization_code
|
||||
&client_id=T70hJ3ls5VTYG8ylX3CZsfIu
|
||||
&client_secret=YABbyHQShPeO1T3NDQZP8q5m3Jpb_UPNmIzqhLDCScSnRyVG
|
||||
&redirect_uri=${REDIRECT_URI}
|
||||
&code=N949tDLuf9ai_DaOKyuFBXStCNMQzuQbtC1QbvLv-AXqPJ_f
|
||||
```
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The client's credentials are included in the `POST` body in this example. Other authorization servers may require that the credentials are sent as a HTTP Basic Authentication header.
|
||||
|
||||
#### Token Endpoint Response
|
||||
|
||||
Finally, you can read the access token from the HTTP response and pass it to the extension UI by having the browser after OAuth be redirected to the backend service. The backend service, in turn, will have to explicitly redirect the browser to `docker-desktop://dashboard/open`.
|
||||
|
||||
## Store the access token
|
||||
|
||||
At the time of this writing, the Docker Extensions SDK does not provide a mechanism to safely store secrets.
|
||||
|
||||
Therefore, it is highly recommended to use an external source of storage to store the access token.
|
||||
|
||||
> ** Warning **
|
||||
>
|
||||
> Storing the access token in the client's localStorage would be a security risk as that storage is currently shared amongst all extensions.
|
||||
> {: .warning}
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
title: Distribute your extension
|
||||
description: Docker extension disctribution
|
||||
keywords: Docker, extensions, sdk, distribution
|
||||
---
|
||||
|
||||
## Packaging
|
||||
|
||||
Docker Extensions are packaged as Docker images. The entire extension runtime including the UI, backend services (host or VM) and any necessary binary must be included in the extension image.
|
||||
Every extension image must contain a metadata.json file at the root of its filesystem that [defines the contents of the extension](METADATA.md).
|
||||
|
||||
The image must have [several labels](labels.md):
|
||||
|
||||
- `org.opencontainers.image.title` for the name of the extension.
|
||||
- `org.opencontainers.image.vendor` for the provider for the extension.
|
||||
- `com.docker.desktop.extension.api.version`for the Docker API version the extension is compatible with.
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
## Distribution and new releases
|
||||
|
||||
Releasing a Docker Desktop extension is done by running `docker push` to push the extension image to Docker Hub.
|
||||
|
||||
Docker Desktop includes an allow-list of extensions available to users. The extension image Hub repository (like `mycompany/my-desktop-extension`) must be part of the Docker Desktop allow-list to be recognized as an extension.
|
||||
|
||||
This allow-list specifies which Hub repositories are to be used by Docker Desktop to download and install extensions with a specific version at a given point in time.
|
||||
|
||||
Any new image pushed to a repository that is part of the allow-list corresponds to a new version of the extension. Image tags are used to identify version numbers. Extension versions must follow semver to make it easy to understand and compare versions.
|
||||
|
||||
With a given release of Docker Desktop (including some extensions), users should not need to upgrade Docker Desktop in order to obtain new versions of a specific extension. Newer versions of the extension can be released independently of Docker Desktop releases, provided there is no Extension API mismatchs.
|
||||
|
||||
Docker Desktop scans the list of published extensions for new versions regularly, and provides notifications to users when they can upgrade a specific extension.
|
||||
|
||||
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.
|
||||
|
||||
Docker Desktop can use this Extension API version to detect if a newer version of an extension is valid given the user's current version of Docker Desktop. If it is, the user sees a notification to upgrade the corresponding extension.
|
||||
|
||||
The API version that the extension relies upon must be specified in the extension image labels. This allows Docker Desktop to inspect newer versions of extension images without downloading the full extension image upfront.
|
||||
|
|
@ -0,0 +1,144 @@
|
|||
---
|
||||
title: Extension metadata
|
||||
description: Docker extension metadata
|
||||
keywords: Docker, extensions, sdk, metadata
|
||||
---
|
||||
|
||||
The image for a Docker extension must include a `metadata.json` file at the root of its filesystem. It describes the content of the extension that must be installed to make it work in Docker Desktop.
|
||||
|
||||
With each part being optional, an extension contains:
|
||||
|
||||
- A UI part that adds a tab to the dashboard in Docker Desktop.
|
||||
- A VM service which executes in the Desktop VM as one or several Docker container(s). These containers can request access to specific resources in the VM, for example by mounting folders in the compose file.
|
||||
- A list of binaries to be installed on the host.
|
||||
|
||||
## UI section
|
||||
|
||||
The UI part of the extension is able to communicate at runtime with the extension VM service, or invoke the extension binaries deployed on the host via the Extension API defined below.
|
||||
|
||||
The format of the metadata.json file must be:
|
||||
|
||||
```json
|
||||
{
|
||||
"icon": "extension-icon.svg",
|
||||
"ui": ...
|
||||
"vm": ...
|
||||
"host": ...
|
||||
}
|
||||
```
|
||||
|
||||
The `ui`, `vm`, and `host` sections are optional and depend on what a given extension provides. They describe the extension content to be installed.
|
||||
|
||||
The `ui` section defines a new tab that is added to the dashboard in Docker Desktop. It follows the form:
|
||||
|
||||
```json
|
||||
"ui":{
|
||||
"dashboard-tab":
|
||||
{
|
||||
"title":"MyTitle",
|
||||
"root":"/ui",
|
||||
"src":"index.html"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`root` specifies the folder where the ui code is within the image filesystem.
|
||||
`src` specifies the entrypoint that should be loaded in the extension tab.
|
||||
|
||||
Other UI extension points will be available in the future.
|
||||
|
||||
## VM section
|
||||
|
||||
### Basic extension backend service
|
||||
|
||||
The `vm` section defines a backend service that runs inside the Desktop VM. It must define either an `image` or a `composefile` value that specifies what service to run in the Desktop VM.
|
||||
|
||||
In simple cases you can specify `image` and define the Docker image to be executed for your backend.
|
||||
|
||||
You can use `composefile` if you need more specific options, such as mounting volumes or requesting CAPABILITIES, that can't be expressed just with a Docker image. You can also use a compose file to use multiple backend services.
|
||||
|
||||
In many situations, extension backend services can be defined by using the same image also used to package the extension. This image must then have a defined `CMD` to start the backend service, in addition to `COPY` lines for the extension packaging.
|
||||
|
||||
If you use the same image for the extension packaging and for the backend service, you make packaging/releasing easier in terms or version management or pushing extension images to Docker Hub, for example.
|
||||
|
||||
```json
|
||||
"vm": {
|
||||
"image":"${DESKTOP_PLUGIN_IMAGE}"
|
||||
},
|
||||
```
|
||||
|
||||
The vm metadata section should define either `image` or `composefile`. When you use `image`, a default compose file is generated for the extension.
|
||||
|
||||
> `${DESKTOP_PLUGIN_IMAGE}` is a specific keyword that allows an easy way to refer to the image packaging the extension. It is also possible to specify any other full image name here. However, in many cases using the same image makes things easier for extension development.
|
||||
|
||||
### Define your own compose file for the extension backend
|
||||
|
||||
For more advanced use cases, the extension can also:
|
||||
|
||||
- Specify a custom compose file.
|
||||
- Start several containers for the VM extension service.
|
||||
- Mount volumes in the VM.
|
||||
- Require specific CAPABILITIES.
|
||||
|
||||
```json
|
||||
"vm": {
|
||||
"composefile":"docker-compose.yaml"
|
||||
},
|
||||
```
|
||||
|
||||
The composefile, with a volume definition for example, would look like:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
myExtension:
|
||||
image: ${DESKTOP_PLUGIN_IMAGE}
|
||||
volumes:
|
||||
- /host/path:/container/path
|
||||
```
|
||||
|
||||
### Use the docker socket from your extension backend
|
||||
|
||||
Docker extensions can invoke Docker commands directly from the frontend with the SDK. In some cases, it is useful to also interact with the Docker engine from the backend. Extension backend containers can mount the Docker socket and use it to interact with the Docker engine from the extension backend logic. (Learn more about the [Docker engine socket](https://docs.docker.com/engine/reference/commandline/dockerd/#examples))
|
||||
|
||||
However, when mounting the docker socket from an extension container that lives in the Desktop virtual machine, you want to mount the Docker socket from inside the VM, and not mount `/var/run/docker.sock` from the host filsystem (using the Docker socket from the host can lead to permission issues in containers).
|
||||
In order to do so, you can use `/var/run/docker.sock.raw`. Docker Desktop mounts the socket that lives in the Desktop VM, and not from the host.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
myExtension:
|
||||
image: ${DESKTOP_PLUGIN_IMAGE}
|
||||
volumes:
|
||||
- /var/run/docker.sock.raw:/var/run/docker.sock
|
||||
```
|
||||
|
||||
## Host section
|
||||
|
||||
The `host` section defines a few binaries that must be deployed on the host. The UI is able to invoke these binaries through JavaScript APIs. See [invoking an extension binary on the host](../dev/api/backend.md#invoke-an-extension-binary-on-the-host).
|
||||
|
||||
```json
|
||||
"host": {
|
||||
"binaries": [
|
||||
{
|
||||
"darwin": [
|
||||
{
|
||||
"path": "/darwin/myBinary"
|
||||
},
|
||||
],
|
||||
"windows": [
|
||||
{
|
||||
"path": "/windows/myBinary.exe"
|
||||
},
|
||||
],
|
||||
"linux": [
|
||||
{
|
||||
"path": "/linux/myBinary"
|
||||
},
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`binaries` defines a list of binaries to be copied from the extension image to the host.
|
||||
|
||||
`path` specifies the binary path in the image filesystem. Docker Desktop is responsible for copying these files in its own location, and the JavaScript API allows invokes these binaries.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 801 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 585 KiB |
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: Extension image labels
|
||||
description: Docker extension labels
|
||||
keywords: Docker, extensions, sdk, labels
|
||||
---
|
||||
|
||||
[Labels](https://docs.docker.com/engine/reference/builder/#label) are specified in the extension's `Dockerfile` and used to provide information about the extension.
|
||||
|
||||
| Label | Required | Description | Example |
|
||||
| --- | --- | --- | ---|
|
||||
| `org.opencontainers.image.title` | Yes | Human-readable title of the image (string). This appears in the UI for Docker Desktop. | my-extension |
|
||||
| `org.opencontainers.image.description` | Yes | Human-readable description of the software packaged in the image (string) | This extension is cool.|
|
||||
| `org.opencontainers.image.vendor` | Yes | Name of the distributing entity, organization, or individual. | Acme, Inc. |
|
||||
| `com.docker.desktop.extension.api.version` | Yes | Version of the Docker Extension manager that the extension is compatible with. It must follow [semantic versioning](https://semver.org/). | A specific version like `0.1.0` or, a constraint expression: `>= 0.1.0`, `>= 1.4.7, < 2.0` . For your first extension, you can use `docker extension version` to know the SDK API version and specify `>= <SDK_API_VERSION>`.|
|
||||
| `com.docker.desktop.extension.icon` | No | The extension icon (format: .svg .png .jpg) | <a href="https://docs.docker.com/images/engine.svg" target="__blank">https://docs.docker.com/images/engine.svg<a> |
|
||||
| `com.docker.extension.screenshots` | No | A JSON array of image URLs and an alternative text displayed to users (in the order they appear in your metadata) in your extension's details page. | `"[{"alt":"alternative text for image 1",` `"url":"https://foo.bar/image1.png"},` `{"alt":"alternative text for image2",` `"url":"https://foo.bar/image2.jpg"}]"` |
|
||||
| `com.docker.extension.detailed-description` | No | Additional information in plain text or HTML about the extension to be displayed in the details dialog. | `My detailed description` or `<h1>My detailed description</h1>` |
|
||||
| `com.docker.extension.publisher-url` | No | The publisher website URL to be displayed in the details dialog. | `https://foo.bar` |
|
||||
| `com.docker.extension.additional-urls` | No | A JSON array of titles and additional URLs displayed to users (in the order they appear in your metadata) in your extension's details page. We recommend you display the following links if they apply: documentation, support, terms of service, and privacy policy links. | `[{"title":"Documentation","url":"https://foo.bar/docs"},` `{"title":"Support","url":"https://foo.bar/support"},` `{"title":"Terms of Service","url":"https://foo.bar/tos"},` `{"title":"Privacy policy","url":"https://foo.bar/privacy-policy"}]` |
|
||||
| `com.docker.extension.changelog` | No | Changelog in plain text or HTML containing the change for the current version only. | `Extension changelog` or `<p>Extension changelog<ul>` `<li>New feature A</li>` `<li>Bug fix on feature B</li></ul></p>` |
|
||||
|
||||
> Missing required labels
|
||||
>
|
||||
> If any of the previous _required_ labels are missing in the `Dockerfile`, Docker Desktop considers the extension invalid and does not list it in the Marketplace.
|
||||
|
||||
> HTML content styling
|
||||
>
|
||||
> Docker Desktop CSS styles will be applied to the provided HTML content. You can make sure that it renders nicely [within the marketplace](#preview-the-extension-in-the-marketplace). We recommend that you follow our [Styling guidelines](../design/overview.md).
|
||||
|
||||
## Preview the extension in the Marketplace
|
||||
|
||||
You can validate that the image labels render as you expect.
|
||||
|
||||
When you build and install your unpublished extension, you can preview the extension in the Marketplace "installed" tab. You can see how the extension labels are rendered in the list and in the details page of the extension.
|
||||
|
||||
> Preview extensions already listed in Marketplace
|
||||
>
|
||||
> When you install a local image of an extension already published in the Marketplace, for example with the tag `latest`, your local image is currently not detected as "unpublished".
|
||||
>
|
||||
> You can retag your image in order to have a different image name that is not listed as a published extension.
|
||||
> Use `docker tag org/published-extension unpublished-extension` and then `docker extension install unpublished-extension`.
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,118 @@
|
|||
---
|
||||
title: Building multi-arch extensions
|
||||
description: Docker extension multi-arch
|
||||
keywords: Docker, extensions, sdk, multi-arch
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
At a minimum, you must ensure 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.
|
||||
|
||||
## Building and pushing 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`.
|
||||
|
||||
You can do `make push-extension` to build your extension against both `linux/amd64` and `linux/arm64` platforms, and push them to DockerHub.
|
||||
|
||||
Alternatively, if you do not want to use the provided `Makefile`, you can use the command below to build your extension for multiple architectures:
|
||||
|
||||
```cli
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
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
|
||||
WORKDIR /tmp
|
||||
RUN apk add --no-cache curl tar
|
||||
ARG TARGETARCH
|
||||
RUN <<EOT ash
|
||||
mkdir -p /out/darwin
|
||||
curl -fSsLo /out/darwin/kubectl "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/darwin/${TARGETARCH}/kubectl"
|
||||
chmod a+x /out/darwin/kubectl
|
||||
EOT
|
||||
RUN <<EOT ash
|
||||
if [ "amd64" = "$TARGETARCH" ]; then
|
||||
mkdir -p /out/windows
|
||||
curl -fSsLo /out/windows/kubectl.exe "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/windows/amd64/kubectl.exe"
|
||||
fi
|
||||
EOT
|
||||
|
||||
FROM alpine
|
||||
LABEL org.opencontainers.image.title="example-extension" \
|
||||
org.opencontainers.image.description="My Example Extension" \
|
||||
org.opencontainers.image.vendor="Docker Inc." \
|
||||
com.docker.desktop.extension.api.version=">= 0.1.0"
|
||||
|
||||
COPY --from=dl /out /
|
||||
```
|
||||
|
||||
In the `metadata.json` file, we specify the path for every binary on every platform:
|
||||
|
||||
```json
|
||||
{
|
||||
"icon": "docker.svg",
|
||||
"ui": {
|
||||
"dashboard-tab": {
|
||||
"title": "Example Extension",
|
||||
"src": "index.html",
|
||||
"root": "ui"
|
||||
}
|
||||
},
|
||||
"host": {
|
||||
"binaries": [
|
||||
{
|
||||
"darwin": [
|
||||
{
|
||||
"path": "/darwin/kubectl"
|
||||
}
|
||||
],
|
||||
"windows": [
|
||||
{
|
||||
"path": "/windows/kubectl.exe"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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?
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
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).
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 603 KiB |
|
|
@ -0,0 +1,100 @@
|
|||
---
|
||||
title: Introduction
|
||||
description: Overall index for Docker Extensions SDK documentation
|
||||
keywords: Docker, Extensions, sdk
|
||||
---
|
||||
|
||||
Use the resources in this section to create your own Docker Extension.
|
||||
|
||||
> Beta
|
||||
>
|
||||
> 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).
|
||||
|
||||
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
|
||||
|
||||
Before you create your own extension, you need a specific Docker Desktop build that comes with extension capabilities.
|
||||
|
||||
From the [releases page](https://github.com/docker/extensions-sdk/releases/latest), install both the Docker Desktop build and the Extensions CLI which is used to manage extensions later on.
|
||||
|
||||
> Using the CLI to install unpublished extensions
|
||||
>
|
||||
> Extensions can install binaries, invoke commands and access files on your machine. Make sure you trust extensions before installing them on your machine.
|
||||
> {: .warning}
|
||||
|
||||
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>
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 526 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 542 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 555 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 165 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 512 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 566 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 541 KiB |
|
|
@ -0,0 +1,154 @@
|
|||
---
|
||||
title: Extensions SDK tutorials
|
||||
description: index for Docker Extensions SDK tutorials
|
||||
keywords: Docker, Extensions, sdk, tutorial
|
||||
---
|
||||
|
||||
Learn how to create a new Docker extension.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Docker Desktop build with Extensions capabilities](https://github.com/docker/extensions-sdk/releases/)
|
||||
- [Docker Extensions CLI](https://github.com/docker/extensions-sdk/releases/)
|
||||
- [NodeJS](https://nodejs.org)
|
||||
- [Go](https://go.dev/dl/)
|
||||
|
||||
> Note
|
||||
>
|
||||
> 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.
|
||||
|
||||
## Create a new extension
|
||||
|
||||
To create a new extension, use the `init` subcommand and provide a name for your extension.
|
||||
|
||||
```bash
|
||||
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 to 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.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
`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:
|
||||
|
||||
```
|
||||
? Hub repository (eg. namespace/repository on hub): john/my-extension
|
||||
```
|
||||
|
||||
The `make build-extension` generates an image with name `john/my-extension`.
|
||||
|
||||
## Install the extension
|
||||
|
||||
To install the extension in Docker Desktop, run:
|
||||
|
||||
```bash
|
||||
docker extension install john/my-extension
|
||||
```
|
||||
|
||||
If the installation is successful, the following output displays:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 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
|
||||
ID PROVIDER VERSION UI VM HOST
|
||||
john/my-extension Docker Inc. 1 tab(My-Extension) Running(1) -
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
```
|
||||
|
|
@ -0,0 +1,225 @@
|
|||
---
|
||||
title: Minimal backend extension tutorial
|
||||
description: Minimal backend extension tutorial
|
||||
keywords: Docker, extensions, sdk, tutorial
|
||||
---
|
||||
|
||||
Learn how to create 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 build with Extensions capabilities](https://github.com/docker/extensions-sdk/releases/)
|
||||
- [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.
|
||||
|
||||
```bash
|
||||
.
|
||||
├── Dockerfile # (1)
|
||||
├── Makefile
|
||||
├── client # (2)
|
||||
│ └── src
|
||||
│ ├── App.tsx
|
||||
│ └── ... React aplication
|
||||
├── hello.sh # (3)
|
||||
└── metadata.json # (4)
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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`.
|
||||
|
||||
```typescript
|
||||
const ddClient = createDockerDesktopClient();
|
||||
const [backendInfo, setBackendInfo] = useState<string | undefined>();
|
||||
|
||||
async function runExtensionBackend(inputText: string) {
|
||||
const result = await ddClient.extension.vm?.cli.exec("./hello.sh", [
|
||||
inputText,
|
||||
]);
|
||||
setBackendInfo(result?.stdout);
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
- The source code which in this case is an `index.html` that sits within the `ui` folder. `index.html` refers to javascript code in `script.js`.
|
||||
- The `metadata.json` file.
|
||||
|
||||
```Dockerfile
|
||||
FROM node:17.7-alpine3.14 AS client-builder
|
||||
# ... build React application
|
||||
|
||||
FROM alpine:3.15
|
||||
|
||||
LABEL org.opencontainers.image.title="HelloBackend" \
|
||||
org.opencontainers.image.description="A sample extension that runs a shell script inside a container's Desktop VM." \
|
||||
org.opencontainers.image.vendor="Docker Inc." \
|
||||
com.docker.desktop.extension.api.version="1.0.0-beta.1" \
|
||||
com.docker.desktop.extension.icon="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png"
|
||||
|
||||
COPY hello.sh .
|
||||
COPY metadata.json .
|
||||
COPY --from=client-builder /app/client/dist ui
|
||||
|
||||
CMD [ "sleep", "infinity" ]
|
||||
```
|
||||
|
||||
## Configure the metadata file
|
||||
|
||||
A `metadata.json` file is required at the root of the image filesystem.
|
||||
|
||||
```json
|
||||
{
|
||||
"vm": {
|
||||
"image": "${DESKTOP_PLUGIN_IMAGE}"
|
||||
},
|
||||
"ui": {
|
||||
"dashboard-tab": {
|
||||
"title": "Hello Backend Extension",
|
||||
"root": "/ui",
|
||||
"src": "index.html"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 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.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
>
|
||||
> 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 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
|
||||
```
|
||||
|
|
@ -0,0 +1,241 @@
|
|||
---
|
||||
title: Minimal frontend extension tutorial
|
||||
description: Minimal frontend extension tutorial
|
||||
keywords: Docker, extensions, sdk, tutorial
|
||||
---
|
||||
|
||||
Learn how to create a minimal frontend extension based on plain HTML.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Docker Desktop build with Extensions capabilities](https://github.com/docker/extensions-sdk/releases/)
|
||||
- [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-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.
|
||||
|
||||
```bash
|
||||
.
|
||||
├── Dockerfile # (1)
|
||||
├── metadata.json # (2)
|
||||
└── ui # (3)
|
||||
└── index.html
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
- The source code which in this case is an `index.html` that sits within the `ui` folder.
|
||||
- The `metadata.json` file.
|
||||
|
||||
```Dockerfile
|
||||
FROM scratch
|
||||
|
||||
LABEL org.opencontainers.image.title="MinimalFrontEnd" \
|
||||
org.opencontainers.image.description="A sample extension to show how easy it's to get started with Desktop Extensions." \
|
||||
org.opencontainers.image.vendor="Docker Inc." \
|
||||
com.docker.desktop.extension.api.version="1.0.0-beta.1" \
|
||||
com.docker.desktop.extension.icon="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png"
|
||||
|
||||
COPY ui ./ui
|
||||
COPY metadata.json .
|
||||
```
|
||||
|
||||
## Configure the metadata file
|
||||
|
||||
A `metadata.json` file is required at the root of the image filesystem.
|
||||
|
||||
```json
|
||||
{
|
||||
"ui": {
|
||||
"dashboard-tab": {
|
||||
"title": "Min FrontEnd Extension",
|
||||
"root": "/ui",
|
||||
"src": "index.html"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## What's next?
|
||||
|
||||
Learn how to [create an extension using React.](./react-extension.md)
|
||||
|
|
@ -0,0 +1,222 @@
|
|||
---
|
||||
title: Minimal docker CLI extension tutorial
|
||||
description: Minimal docker CLI extension tutorial
|
||||
keywords: Docker, extensions, sdk, tutorial
|
||||
---
|
||||
|
||||
Learn how to create a simple Docker extension that invokes Docker CLI commands.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Docker Desktop build with Extensions capabilities](https://github.com/docker/extensions-sdk/releases/)
|
||||
- [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-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.
|
||||
|
||||
```bash
|
||||
.
|
||||
├── Dockerfile # (1)
|
||||
├── metadata.json # (2)
|
||||
└── client # (3)
|
||||
│ └── src
|
||||
│ ├── App.tsx
|
||||
│ └── ... React aplication
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
We can invoke a Docker command with `ddClient.docker.cli.exec()`.
|
||||
For example, to run `docker info` and obtain json formatted results:
|
||||
|
||||
{% raw %}`ddClient.docker.cli.exec("info", ["--format", '"{{ json . }}"'])`{% endraw %}.
|
||||
|
||||
We can use `result.parseJsonObject()` to read results as a json object and use it in our application.
|
||||
|
||||
```typescript
|
||||
const ddClient = createDockerDesktopClient();
|
||||
const [dockerInfo, setDockerInfo] = useState<any>(null);
|
||||
|
||||
async function runDockerInfo() {
|
||||
const result = await ddClient.docker.cli.exec("info", [
|
||||
"--format",
|
||||
{% raw %}'"{{json .}}"',{% endraw %}
|
||||
]);
|
||||
setDockerInfo(result.parseJsonObject());
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
- The source code which in this case is an `index.html` that sits within the `ui` folder. `index.html` refers to javascript code in `script.js`.
|
||||
- The `metadata.json` file.
|
||||
|
||||
```Dockerfile
|
||||
FROM node:17.7-alpine3.14 AS client-builder
|
||||
# ... build React application
|
||||
|
||||
FROM scratch
|
||||
|
||||
LABEL org.opencontainers.image.title="MyExtension" \
|
||||
org.opencontainers.image.description="A sample extension to show how easy it's to get started with Desktop Extensions." \
|
||||
org.opencontainers.image.vendor="Docker Inc." \
|
||||
com.docker.desktop.extension.api.version="1.0.0-beta.1" \
|
||||
com.docker.desktop.extension.icon="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png"
|
||||
|
||||
COPY ui ./ui
|
||||
COPY metadata.json .
|
||||
```
|
||||
|
||||
## Configure the metadata file
|
||||
|
||||
A `metadata.json` file is required at the root of the image filesystem.
|
||||
|
||||
```json
|
||||
{
|
||||
"ui": {
|
||||
"dashboard-tab": {
|
||||
"title": "Docker VM info",
|
||||
"root": "/ui",
|
||||
"src": "index.html"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## What's next?
|
||||
|
||||
Learn how to [create a minimal backend extension.](./minimal-backend-extension.md)
|
||||
|
|
@ -0,0 +1,239 @@
|
|||
---
|
||||
title: Minimal react extension tutorial
|
||||
description: Minimal react extension tutorial
|
||||
keywords: Docker, extensions, sdk, tutorial
|
||||
---
|
||||
|
||||
Learn how to create a simple Docker extension that contains only a UI part and is based on ReactJS.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Docker Desktop build with Extensions capabilities](https://github.com/docker/extensions-sdk/releases/)
|
||||
- [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 `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.
|
||||
|
||||
```bash
|
||||
.
|
||||
├── Dockerfile # (1)
|
||||
├── client # (2)
|
||||
│ ├── package.json
|
||||
│ ├── public # (3)
|
||||
│ │ └── index.html
|
||||
│ ├── src # (4)
|
||||
│ │ ├── App.tsx
|
||||
│ │ ├── globals.d.ts
|
||||
│ │ ├── index.tsx
|
||||
│ │ └── react-app-env.d.ts
|
||||
│ ├── tsconfig.json
|
||||
│ └── yarn.lock
|
||||
├── docker.svg # (5)
|
||||
└── metadata.json # (6)
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Create a Dockerfile
|
||||
|
||||
An extension requires a `Dockerfile` to build, publish, and run in Docker Desktop.
|
||||
|
||||
```Dockerfile
|
||||
FROM node:14.17-alpine3.13 AS client-builder
|
||||
WORKDIR /app/client
|
||||
# cache packages in layer
|
||||
COPY client/package.json /app/client/package.json
|
||||
COPY client/yarn.lock /app/client/yarn.lock
|
||||
ARG TARGETARCH
|
||||
RUN yarn config set cache-folder /usr/local/share/.cache/yarn-${TARGETARCH}
|
||||
RUN --mount=type=cache,target=/usr/local/share/.cache/yarn-${TARGETARCH} yarn
|
||||
# install
|
||||
COPY client /app/client
|
||||
RUN --mount=type=cache,target=/usr/local/share/.cache/yarn-${TARGETARCH} yarn build
|
||||
|
||||
FROM debian:bullseye-slim
|
||||
LABEL org.opencontainers.image.title="ui-extension" \
|
||||
org.opencontainers.image.description="Your Desktop Extension Description" \
|
||||
org.opencontainers.image.vendor="Docker Inc." \
|
||||
com.docker.desktop.extension.api.version="1.0.0-beta.1" \
|
||||
com.docker.desktop.extension.icon="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png"
|
||||
|
||||
COPY --from=client-builder /app/client/dist ui
|
||||
COPY docker.svg .
|
||||
COPY metadata.json .
|
||||
|
||||
```
|
||||
|
||||
## Configure the metadata file
|
||||
|
||||
A `metadata.json` file is required at the root of your extension directory.
|
||||
|
||||
```json
|
||||
{
|
||||
"icon": "docker.svg",
|
||||
"ui": {
|
||||
"dashboard-tab": {
|
||||
"title": "UI Extension",
|
||||
"root": "/ui",
|
||||
"src": "index.html"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Use extension APIs in the application code
|
||||
|
||||
The React application can import `@docker/extension-api-client` and use extension APIs to perform actions with Docker Desktop.
|
||||
|
||||
```ts
|
||||
import { Box, Button } from '@mui/material';
|
||||
import { createDockerDesktopClient } from '@docker/extension-api-client';
|
||||
|
||||
export function App() {
|
||||
//obtain docker destkop extension client
|
||||
const ddClient = createDockerDesktopClient();
|
||||
|
||||
function sayHello() {
|
||||
ddClient.desktopUI.toast.success('Hello, World!');
|
||||
}
|
||||
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## 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!`.
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## What's next?
|
||||
|
||||
Learn how to [create an extension using Docker CLI commands.](./minimal-frontend-using-docker-cli.md)
|
||||
Loading…
Reference in New Issue