Add a backend to your extension

Your extension can ship a backend part with which the frontend can interact with. This page provides information on why and how to add a backend.

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

Tip

Check the Quickstart guideanddocker extension init <my-extension>.They provide a better base for your extension as it's more up-to-date and related to your install of Docker Desktop.

Why add a backend?

Thanks to the Docker Extensions SDK, most of the time you should be able to do what you need from the Docker CLI directly from the frontend.

Nonetheless, there are some cases where you might need to add a backend to your extension. So far, extension builders have used the backend to:

• Store data in a local database and serve them back with a REST API.
• Store the extension state, for example when a button starts a long-running process, so that if you navigate away from the extension user interface and comes back, the frontend can pick up where it left off.

For more information about extension backends, see Architecture.

Add a backend to the extension

If you created your extension using thedocker extension initcommand, you already have a backend setup. Otherwise, you have to first create avmdirectory that contains the code and updates the Dockerfile to containerize it.

Here is the extension folder structure with a backend:

.
├── Dockerfile# (1)
├── Makefile
├── metadata.json
├── ui
└── index.html
└── vm# (2)
├── go.mod
└── main.go

1. Contains everything required to build the backend and copy it in the extension's container filesystem.
2. The source folder that contains the backend code of the extension.

Although you can start from an empty directory or from thevm-ui extension sample, it is highly recommended that you start from thedocker extension initcommand and change it to suit your needs.

Tip

Thedocker extension initgenerates a Go backend. But you can still use it as a starting point for your own extension and use any other language like Node.js, Python, Java,.Net, or any other language and framework.

In this tutorial, the backend service simply exposes one route that returns a JSON payload that says "Hello".

{"Message":"Hello"}

Important

We recommend that, the frontend and the backend communicate through sockets, and named pipes on Windows, instead of HTTP. This prevents port collision with any other running application or container running on the host. Also, some Docker Desktop users are running in constrained environments where they can't open ports on their machines. When choosing the language and framework for your backend, make sure it supports sockets connection.

packagemain

import(
"flag"
"log"
"net"
"net/http"
"os"

"github /labstack/echo"
"github /sirupsen/logrus"
)

funcmain(){
varsocketPathstring
flag.StringVar(&socketPath,"socket","/run/guest/volumes-service.sock","Unix domain socket to listen on")
flag.Parse()

os.RemoveAll(socketPath)

logrus.New().Infof("Starting listening on %s\n",socketPath)
router:=echo.New()
router.HideBanner=true

startURL:=""

ln,err:=listen(socketPath)
iferr!=nil{
log.Fatal(err)
}
router.Listener=ln

router.GET("/hello",hello)

log.Fatal(router.Start(startURL))
}

funclisten(pathstring)(net.Listener,error){
returnnet.Listen("unix",path)
}

funchello(ctxecho.Context)error{
returnctx.JSON(http.StatusOK,HTTPMessageBody{Message:"hello world"})
}

typeHTTPMessageBodystruct{
Messagestring
}

Adapt the Dockerfile

Note

When using thedocker extension init,it creates aDockerfilethat already contains what is needed for a Go backend.

# syntax=docker/dockerfile:1
FROMnode:17.7-alpine3.14 AS client-builder
#... build frontend application

# Build the Go backend
FROMgolang:1.17-alpine AS builder
ENVCGO_ENABLED=0
WORKDIR/backend
COPYvm/go.*.
RUN--mount=type=cache,target=/go/pkg/mod\
--mount=type=cache,target=/root/.cache/go-build\
go mod download
COPYvm/..
RUN--mount=type=cache,target=/go/pkg/mod\
--mount=type=cache,target=/root/.cache/go-build\
go build -trimpath -ldflags="-s -w"-o bin/service

FROMalpine:3.15
#... add labels and copy the frontend application

COPY--from=builder /backend/bin/service /
CMD/service -socket /run/guest-services/extension-allthethings-extension.sock

Configure the metadata file

To start the backend service of your extension inside the VM of Docker Desktop, you have to configure the image name in thevmsection of themetadata.jsonfile.

{
"vm":{
"image":"${DESKTOP_PLUGIN_IMAGE}"
},
"icon":"docker.svg",
"ui":{
...
}
}

For more information on thevmsection of themetadata.json,see Metadata.

Warning

Do not replace the${DESKTOP_PLUGIN_IMAGE}placeholder in themetadata.jsonfile. The placeholder is replaced automatically with the correct image name when the extension is installed.

Invoke the extension backend from your frontend

Using the advanced frontend extension example,we can invoke our extension backend.

Use the Docker Desktop Client object and then invoke the/helloroute from the backend service withddClient. extension.vm.service.getthat returns the body of the response.

// ui/src/App.tsx
importReact,{useEffect}from'react';
import{createDockerDesktopClient}from"@docker/extension-api-client";

//obtain docker destkop extension client
constddClient=createDockerDesktopClient();

exportfunctionApp() {
constddClient=createDockerDesktopClient();
const[hello,setHello]=useState<string>();

useEffect(()=>{
constgetHello=async()=>{
constresult=awaitddClient.extension.vm?.service?.get('/hello');
setHello(JSON.stringify(result));
}
getHello()
},[]);

return(
<Typography>{hello}</Typography>
);
}

Re-build the extension and update it

Since you have modified the configuration of the extension and added a stage in the Dockerfile, you must re-build the extension.

docker build --tag=awesome-inc/my-extension:latest.

Once built, you need to update it, or install it if you haven't already done so.

docker extension update awesome-inc/my-extension:latest

Now you can see the backend service running in the *Containers8tab of the Docker Dashboard and watch the logs when you need to debug it.

Tip

You may need to turn on theShow system containersoption inSettingsto see the backend container running. See Show extension containersfor more information.

Open Docker Dashboard and select theContainerstab. You should see the response from the backend service call displayed.

What's next?

• Learn how to share and publish your extension.
• Learn more about extensions architecture.