Ajouter un backend à votre extension

Votre extension peut intégrer une partie backend avec laquelle le frontend peut interagir. Cette page fournit des informations sur pourquoi et comment ajouter un backend.

Avant de commencer, assurez-vous d'avoir installé la dernière version de Docker Desktop.

Astuce

Consultez le Guide de démarrage rapide et docker extension init <my-extension>. Ils fournissent une meilleure base pour votre extension car elle est plus à jour et liée à votre installation de Docker Desktop.

Pourquoi ajouter un backend ?

Grâce au SDK des Extensions Docker, la plupart du temps vous devriez pouvoir faire ce dont vous avez besoin depuis la CLI Docker directement depuis le frontend.

Néanmoins, il y a certains cas où vous pourriez avoir besoin d'ajouter un backend à votre extension. Jusqu'à présent, les développeurs d'extensions ont utilisé le backend pour :

• Stocker des données dans une base de données locale et les servir de nouveau avec une API REST.
• Stocker l'état de l'extension, par exemple quand un bouton démarre un processus de longue durée, de sorte que si vous naviguez loin de l'interface utilisateur de l'extension et revenez, le frontend peut reprendre là où il s'était arrêté.

Pour plus d'informations sur les backends d'extensions, voir Architecture.

Ajouter un backend à l'extension

Si vous avez créé votre extension en utilisant la commande docker extension init, vous avez déjà un backend configuré. Sinon, vous devez d'abord créer un répertoire vm qui contient le code et mettre à jour le Dockerfile pour le conteneuriser.

Voici la structure de dossiers de l'extension avec un backend :

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

1. Contient tout ce qui est requis pour construire le backend et le copier dans le système de fichiers du conteneur de l'extension.
2. Le dossier source qui contient le code backend de l'extension.

Bien que vous puissiez partir d'un répertoire vide ou de l'exemple vm-ui extension sample, il est fortement recommandé de partir de la commande docker extension init et de la modifier selon vos besoins.

Tip

La commande docker extension init génère un backend Go. Mais vous pouvez toujours l'utiliser comme point de départ pour votre propre extension et utiliser n'importe quel autre langage comme Node.js, Python, Java, .Net, ou tout autre langage et framework.

Dans ce tutoriel, le service backend expose simplement une route qui retourne un payload JSON qui dit "Hello".

{ "Message": "Hello" }

Important

Nous recommandons que le frontend et le backend communiquent à travers des sockets, et des pipes nommés sur Windows, au lieu de HTTP. Cela évite les collisions de ports avec toute autre application en cours d'exécution ou conteneur s'exécutant sur l'hôte. De plus, certains utilisateurs de Docker Desktop s'exécutent dans des environnements contraints où ils ne peuvent pas ouvrir de ports sur leurs machines. Lors du choix du langage et du framework pour votre backend, assurez-vous qu'il supporte les connexions par sockets.

package main

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

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

func main() {
	var socketPath string
	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)
	if err != nil {
		log.Fatal(err)
	}
	router.Listener = ln

	router.GET("/hello", hello)

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

func listen(path string) (net.Listener, error) {
	return net.Listen("unix", path)
}

func hello(ctx echo.Context) error {
	return ctx.JSON(http.StatusOK, HTTPMessageBody{Message: "hello world"})
}

type HTTPMessageBody struct {
	Message string
}

Adapter le Dockerfile

Note

Lors de l'utilisation de docker extension init, cela crée un Dockerfile qui contient déjà ce qui est nécessaire pour un backend Go.

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

# Build the Go backend
FROM golang:1.17-alpine AS builder
ENV CGO_ENABLED=0
WORKDIR /backend
COPY vm/go.* .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go mod download
COPY vm/. .
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

FROM alpine: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

Configurer le fichier de métadonnées

Pour démarrer le service backend de votre extension à l'intérieur de la VM de Docker Desktop, vous devez configurer le nom de l'image dans la section vm du fichier metadata.json.

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

Pour plus d'informations sur la section vm du metadata.json, voir Metadata.

Warning

Ne remplacez pas le placeholder ${DESKTOP_PLUGIN_IMAGE} dans le fichier metadata.json. Le placeholder est remplacé automatiquement par le nom d'image correct lorsque l'extension est installée.

Invoquer le backend de l'extension depuis votre frontend

En utilisant l'exemple d'extension frontend avancé, nous pouvons invoquer notre backend d'extension.

Utilisez l'objet Client Docker Desktop puis invoquez la route /hello depuis le service backend avec ddClient. extension.vm.service.get qui retourne le corps de la réponse.

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

//obtain docker desktop extension client
const ddClient = createDockerDesktopClient();

export function App() {
  const ddClient = createDockerDesktopClient();
  const [hello, setHello] = useState<string>();

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

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

Reconstruire l'extension et la mettre à jour

Puisque vous avez modifié la configuration de l'extension et ajouté une étape dans le Dockerfile, vous devez reconstruire l'extension.

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

Une fois construite, vous devez la mettre à jour, ou l'installer si vous ne l'avez pas encore fait.

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

Maintenant vous pouvez voir le service backend s'exécuter dans la vue Containers du Tableau de bord Docker Desktop et regarder les logs quand vous avez besoin de le déboguer.

Tip

Vous pourriez avoir besoin d'activer l'option Show system containers dans Settings pour voir le conteneur backend s'exécuter. Voir Show extension containers pour plus d'informations.

Ouvrez le Tableau de bord Docker Desktop et sélectionnez l'onglet Containers. Vous devriez voir la réponse de l'appel du service backend s'afficher.

Et maintenant ?

• Apprenez comment partager et publier votre extension.
• Apprenez-en plus sur l'architecture des extensions.