docs/desktop/extensions-sdk/build/set-up/minimal-frontend-using-docker-cli.md

title	description	keywords	redirect_from
Set up a minimal extension invoking Docker commands	Minimal docker CLI extension tutorial	Docker, extensions, sdk, build	/desktop/extensions-sdk/tutorials/minimal-frontend-using-docker-cli/

To start creating your extension, you first need a directory with files which range from the extension’s source code to the required extension-specific files. This page provides information on how to set up a simple Docker extension that invokes Docker CLI commands.

Note

Before you start, make sure you have installed the latest version of Docker Desktop.

Extension folder structure

In the minimal-docker-cli sample folder, 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.

.
├── Dockerfile # (1)
├── metadata.json # (2)
└── client # (3)
│   └── src
│       ├── App.tsx
│       └── ... React application

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. For more information and guidelines on building the UI, see the Design and UI styling section.

If you want to set up user authentication for the extension, see Authentication.

Invoke docker CLI in your javascript code

Using the React extension example, 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.

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

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.

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.

{
  "ui": {
    "dashboard-tab": {
      "title": "Docker VM info",
      "root": "/ui",
      "src": "index.html"
    }
  }
}

For more information on the metadata.json, see Metadata.

What's next?

Learn how to build and install your extension.