Déployer des applications sur Heroku avec Experience Orchestration dans Oracle Content Management

Introduction

Heroku est une plate-forme cloud qui vous permet de créer, de distribuer, de surveiller et d'adapter des applications.

Le déploiement d'une application sur Heroku est une opération simple qui ne nécessite que quelques étapes simples pour les applications de base, mais peut également prendre en charge de nombreux paramètres avancés pour des scénarios plus complexes.

Dans ce tutoriel, nous allons déployer une application sur Heroku à partir d'une source GitHub en utilisant les fonctionnalités d'orchestration de l'expérience dans Oracle Content Management. Oracle Content Management permet de connecter des référentiels de contenu et des canaux de publication à des expériences en mode Headless développées et gérées en dehors d'Oracle Content Management, et de déclencher automatiquement des déploiements en fonction des modifications de contenu ou du statut publié.

Le tutoriel se compose des étapes suivantes :

  1. Créer une application Heroku
  2. Créer une expérience d'Oracle Content Management
  3. Configuration de webhooks sortants
  4. Configuration de webhooks entrants
  5. (Facultatif) Ajoutez des webhooks sortants/entrants supplémentaires pour l'aperçu de contenu
  6. Analyser les événements

Prérequis

Avant de poursuivre ce tutoriel, nous vous recommandons de lire les informations suivantes en premier :

Pour suivre ce tutoriel, vous aurez besoin des éléments suivants :

Tâche 1 : Créer une application Heroku

Si vous ne disposez pas encore d'une instance Oracle Content Management, reportez-vous à Démarrage rapide pour savoir comment vous inscrire à Oracle Cloud, provisionner une instance Oracle Content Management et configurer Oracle Content Management en tant que CMS sans tête.

Si vous n'avez pas encore de compte Heroku, vous devrez créer un compte Heroku. Le niveau gratuit dispose de privilèges suffisants pour déployer les applications Heroku les plus simples.

Si vous n'avez pas encore de compte GitHub, vous devrez créer un compte GitHub. Un compte gratuit de base est tout ce dont vous avez besoin pour insérer votre code source. Votre code source peut être un référentiel public ou privé.

Une fois tous ces éléments configurés, connectons Heroku à GitHub et déployons une application :

  1. Connectez-vous à Heroku et choisissez Personnel ou Equipe en haut à gauche en fonction de votre cas d'emploi.

    Cette image montre le paramètre personnel vs. équipe.

  2. Cliquez sur Nouveau dans le menu déroulant en haut à droite, puis choisissez Créer une application.

    Cette image montre le processus de création de l'application.

  3. Attribuez un nom à votre application et cliquez sur Créer une application.

    Cette image présente le processus de dénomination de l'application.

  4. Ouvrez l'onglet Déployer et connectez-vous à GitHub en recherchant votre référentiel et sélectionnez celui que vous souhaitez déployer. Si vous avez l'intention de déployer la dernière version de l'application, ce paramètre peut rester "principal" (valeur par défaut). Si c'est la première fois que vous créez un site à partir de ce fournisseur, vous serez invité à donner à Heroku l'autorisation d'accéder à vos référentiels. Pour ce faire, suivez les invites.

    Cette image présente le processus de connexion de référentiel GitHub.

    Cette image montre le paramètre personnel vs. équipe.

  5. Pour la première fois, vous devez cliquer sur Déployer la branche dans la section Déploiement manuel. Si vous souhaitez activer les déploiements automatiques, activez-les dans la section Déploiements automatiques.

    Cette image présente l'étape de déploiement finale.

Remarques :

Exemple de référentiel Vue pour le déploiement d'Heroku

Cette section est facultative, mais fournit un exemple de référentiel d'échantillons de blog Vue qui peut facilement être déployé à Heroku. Le référentiel se trouve sur GitHub.

Un tutoriel sur la configuration de l'exemple de blog Vue est disponible dans Oracle Help Center, notamment une présentation vidéo. Une certaine configuration de cet exemple peut être nécessaire sur votre système, par exemple pour modifier le fichier .env et charger des données sur votre serveur, comme indiqué dans le tutoriel.

Vous pouvez créer un nouveau référentiel dans votre compte en accédant au référentiel GitHub et en cliquant sur " porc ".

Forking Vue Blog Repository.

Le déplacement d'un référentiel crée une copie du référentiel. Ici, forking un référentiel vous permet d'expérimenter librement les modifications sans affecter le projet d'origine, mais aucune modification n'est nécessaire pour pouvoir déployer cette application sur Heroku.

Une fois que vous avez créé ce projet, vous pouvez continuer et créer votre premier exemple de déploiement, comme indiqué ci-dessus.

Corriger les erreurs CORS potentielles pour votre application Heroku

Cette section vous aide à corriger les erreurs CORS (Cross-Origin Resource Sharing) qui peuvent exister dans votre application. CORS est une norme qui permet à un serveur de relâcher la stratégie de même origine. Ainsi, si l'emplacement de l'application est servi et que l'origine de la ressource demandée est différente, la stratégie de même origine du navigateur Web prend effet et CORS est requis pour que la requête soit effectuée.

Vous pouvez l'activer dans l'interface Web d'Oracle Content Management en accédant à Système, puis à Sécurité. Ajoutez l'URL de l'application Heroku à Front Channel CORS Origins, puis cliquez sur Enregistrer.

Ajout de l'URL de l'application Heroku aux origines CORS du canal frontal.

Remarque : selon la stratégie de même origine, deux URL ont la même origine si et seulement si elles partagent exactement le même protocole, domaine et port. Cela signifie que vous devrez peut-être ajouter des URL http et https dans cette section.

Tâche 2 : Créer une expérience Oracle Content Management

Dans la tâche précédente, nous avons connecté Heroku à GitHub. Nous allons maintenant créer un objet d'expérience Oracle Content Management, qui sera connecté à Heroku ultérieurement.

Pour créer un objet d'expérience dans Oracle Content Management :

  1. Connectez-vous à l'interface Web d'Oracle Content Management en tant qu'administrateur.

  2. Cliquez sur Experiences dans le panneau de navigation de gauche, puis sur Créer en haut à droite.

    Cette image présente la création d'un objet d'expérience dans l'interface Web Oracle Content Management.

  3. Entrez les informations requises et cliquez sur Créer une fois que vous avez terminé. Pour plus d'informations, reportez-vous à la documentation Oracle Content Management.

    Cette image présente les propriétés de configuration d'un objet d'expérience.

Tâche 3 : Configurer les webhooks sortants

Ensuite, nous allons configurer le webhook sortant pour l'objet d'expérience Oracle Content Management nouvellement créé. Le webhook sortant est destiné à déclencher automatiquement des déploiements d'Oracle Content Management vers Heroku en fonction des modifications de contenu ou du statut publié.

Pour configurer les webhooks sortants :

  1. Connectez-vous à l'interface Web d'Oracle Content Management en tant qu'administrateur.

  2. Cliquez sur Experiences dans le panneau de navigation de gauche.

  3. Sélectionnez l'expérience que vous souhaitez configurer, puis ouvrez le panneau Propriétés.

    Cette image montre comment rechercher les propriétés d'un objet d'expérience.

  4. Dans le panneau Propriétés, ouvrez l'onglet Sortant.

    Cette image montre l'onglet Sortant d'un objet d'expérience.

  5. Configurez le nom de la cible, de la méthode (GET ou POST), de l'adresse d'URL et du déclencheur pour la demande.

    • Nom de la cible : vous pouvez attribuer à la cible le nom de votre choix. Oracle Content Management fournira un TARGET_IDENTIFIER unique pour cette cible.

    • Méthode : indiquez GET ou POST dans la demande via le menu déroulant. Pour Heroku, nous voulons faire une demande POST pour déclencher un build.

    • Adresse d'URL : adresse d'API. Pour Heroku, nous allons utiliser l'adresse https://api.heroku.com/apps/NAME-OF-YOUR-HEROKU-APP/builds, où NAME-OF-YOUR-HEROKU-APP doit être remplacé en conséquence.

    • Déclencheur de demande : dans l'onglet Contenu, où vous pouvez spécifier un déclencheur en fonction d'un événement spécifique. Dans l'exemple ci-dessous, un build sera déclenché en fonction d'une modification du référentiel de ressources appelée OCEGettingStartedRepository, qui représente le canal Blog dans Oracle Content Management.

    Cette image présente la cible sortante d'un objet d'expérience.

  6. Configurez les en-têtes. Trois en-têtes sont nécessaires : Autorisation, Accepter et Type de contenu. Ces informations sont documentées dans la documentation Heroku.

    • Autorisation : il s'agit d'un jeton d'autorisation que vous devez obtenir auprès de Heroku. Seuls les utilisateurs autorisés peuvent créer des builds à partir de Heroku, et ce jeton est requis pour l'authentification afin d'utiliser l'API Heroku. Vous pouvez afficher votre clé d'API Heroku en accédant à Paramètres du compte > Clé d'API > Afficher.

    • Accepter : Voici l'en-tête d'acceptation : application/vnd.heroku+json; version=3. Pour que cela fonctionne, vous devez utiliser la version 3 de l'API de build Heroku.

    • Content-Type : il s'agit de l'en-tête Content-Type : application/json.

    Cette image montre les en-têtes sortants pour un objet d'expérience.

  7. Configurez le corps. Vous aurez besoin d'un objet BLOB source avec une URL et une version facultative formatée en tant qu'objet JSON comme indiqué ci-dessous. Le BLOB source est l'emplacement du code source pour le déploiement. L'objet JSON pour le corps doit être :

    {"source_blob":{"url":"GITHUB_API_ENDPOINT_FOR_TARBALL", "version":"OPTIONAL_TARGET_IDENTIFIER"}}

    URL

    L'URL à utiliser est l'emplacement où une archive tar compressée du code source du build a été téléchargée. Pour ce faire, nous utilisons l'API de GitHub.

    L'URL des référentiels publics et privés sur GitHub est différente. Pour plus de détails, reportez-vous à la documentation Heroku.

    Pour les référentiels publics, l'URL doit être :

    https://api.github.com/repos/<username>/<repo name>/tarball/<branch>

    Pour les référentiels privés, l'URL doit être :

    https://user:token@api.github.com/repos/<username>/<repo name>/tarball/<branch>

    <username> est votre nom utilisateur GitHub, <repo name> est l'identifiant de votre référentiel GitHub et <branch> est le nom de votre branche (généralement "principal" ou "maître"). Voici un exemple de référentiel public.

    Pour les référentiels privés, vous devez modifier la section user:token pour l'URL de l'objet BLOB source du référentiel privé. La partie user peut être remplacée par le même nom utilisateur qu'auparavant et token doit être remplacé par un jeton d'accès personnel GitHub avec la portée appropriée. Pour générer ce jeton, suivez les étapes décrites dans la documentation GitHub. Accordez une attention particulière à la date d'expiration de ce jeton (vous ne voulez généralement pas qu'il expire) et vous devez donner à ce jeton l'accès "repo" uniquement, ce qui donne un contrôle total sur les référentiels privés.

    version

    Le paramètre de version n'est pas requis et n'est pas utilisé lors du téléchargement et de la création du code source. Il s'agit simplement d'un élément de métadonnées que vous pouvez éventuellement utiliser pour suivre la version du code source utilisée pour créer l'identifiant.

    Dans notre cas, nous ajouterons "{{TARGET_IDENTIFIER}}" comme paramètre de version. Oracle Content Management place l'ID TARGET_IDENTIFIER affiché en regard du nom de la cible dans le corps de la demande. Lorsqu'il est envoyé à Heroku, il est renvoyé via le webhook entrant une fois configuré. Dans cette réponse de Heroku concernant le build, Oracle Content Management reçoit les données traitées et évalue si cet ID cible existe. Si tel est le cas, les données traitées sont associées à la cible sortante d'Oracle Content Management. Sinon, elles sont considérées comme "inconnues". Pour plus d'informations sur les ID cible, reportez-vous à la documentation Oracle Content Management.

    Cette image montre le corps sortant d'un objet d'expérience.

  8. Cliquez sur Appliquer en haut à droite pour enregistrer votre configuration.

  9. Vous pouvez éventuellement cliquer sur Tester en regard de l'adresse d'API pour tester un déclencheur de ce build comme si le contenu ou le statut publié change dans le canal sélectionné.

Remarque : des détails supplémentaires sur la configuration du webhook sortant dans Oracle Content Management sont disponibles dans la documentation Oracle Content Management.

Tâche 4 : Configurer les webhooks entrants

Ensuite, nous allons configurer le webhook entrant de Heroku vers Oracle Content Management pour l'objet d'expérience nouvellement créé. Le webhook entrant est destiné à fournir des informations sur le build et son statut à Oracle Content Management sans quitter Oracle Content Management. Vous pouvez afficher les résultats dans l'onglet Evénements, où vous trouverez plus d'informations lors de l'analyse des événements.

Pour configurer les webhooks entrants, procédez comme suit :

  1. Connectez-vous à l'interface Web d'Oracle Content Management en tant qu'administrateur.

  2. Cliquez sur Experiences dans le panneau de navigation de gauche.

  3. Sélectionnez l'expérience que vous souhaitez configurer, puis ouvrez le panneau Propriétés.

    Cette image montre comment rechercher les propriétés d'un objet d'expérience.

  4. Dans le panneau Propriétés, ouvrez l'onglet Entrant. Copiez l'URL du webhook que nous allons placer dans Heroku.

    Cette image présente l'onglet Entrant d'un objet d'expérience.

  5. Reconnectez-vous à Heroku et trouvez votre application. En haut à droite, cliquez sur Plus, puis sur Afficher les webhooks.

    Cette image montre où voir les webhooks à Heroku.

  6. Cliquez sur Créer un webhook au centre de l'écran.

    Cette image montre où créer des webhooks à Heroku.

  7. Dans la boîte de dialogue Nouveau webhook, fournissez les informations relatives au nouveau webhook. Tout nom est correct, l'URL des données traitées doit être celle copiée à partir d'Oracle Content Management et aucune clé secrète n'est nécessaire. Pour les types d'événement, assurez-vous que seul 'api:build' est sélectionné.

    Cette image montre comment configurer Oracle Content Management en tant que webhook à Heroku.

  8. Cliquez sur Ajouter un webhook lorsque vous avez terminé.

Tâche 5 (facultatif) : Ajouter des webhooks sortants et entrants supplémentaires pour l'aperçu de contenu

Les API REST sont disponibles dans Oracle Content Management pour la diffusion et la gestion de contenu, ainsi que pour les conversations, les documents et les utilisateurs et les groupes. Pour l'intégration avec Heroku, il peut être utile d'avoir deux déploiements distincts sur différentes applications Heroku en utilisant la même expérience pour l'aperçu de contenu et la livraison de contenu afin que les modifications non publiées d'une ressource puissent être prévisualisées dans une application sans affecter la version de production. Dans cette section facultative, nous allons découvrir comment utiliser une deuxième cible de l'expérience pour déclencher un aperçu des déploiements séparément des déploiements de production.

La première étape consiste à créer un total de deux applications Heroku distinctes, où une application Heroku utilisera le contenu de prévisualisation et l'autre le contenu de diffusion. Vous pouvez créer une application Heroku en suivant les instructions de la tâche 1.

Une fois cette configuration effectuée, vous devez configurer les deux cibles sortantes. Vous pouvez ajouter une deuxième cible en cliquant sur Ajouter une cible en bas. Suivez les étapes de la tâche 3 pour créer un webhook sortant. Notez qu'il doit y avoir deux principales différences entre les deux webhooks sortants :

  1. L'API de diffusion de contenu doit être déclenchée en fonction d'une publication dans le canal de contenu. L'API d'aperçu de contenu doit être déclenchée en fonction d'une modification dans le référentiel de contenu.

  2. Le corps du webhook sortant doit être lié au code approprié qui utilise l'API de diffusion de contenu ou l'API d'aperçu de contenu. Vous aurez besoin de votre code d'aperçu et de votre code de livraison hébergés sur deux référentiels GitHub distincts.

    Cette image montre comment configurer les webhooks de distribution et de prévisualisation.

Remarque : pour plus de détails sur l'aperçu de la configuration d'API dans Oracle Content Management, reportez-vous à Utilisation des API d'aperçu dans les sites Oracle Content Management sans tête.

La dernière étape consiste à configurer les webhooks entrants de chaque application Heroku, qui peuvent être effectués en suivant les étapes de la tâche 4 pour chacune des applications. Les deux applications Heroku partageront la même URL de webhook entrante fournie par Oracle Content Management.

Un problème important à noter est que Heroku limite le nombre de constructions simultanées par compte. Heroku permet uniquement aux comptes vérifiés d'exécuter simultanément des versions de plusieurs applications sur un compte, ce qui nécessite un paiement supplémentaire pour Heroku. Si vous utilisez la version gratuite de Heroku intégrée à la fonctionnalité d'orchestration de l'expérience d'Oracle Content Management sur deux applications Heroku sous le même compte, vous devrez peut-être attendre la fin des builds avant d'effectuer une autre modification dans un référentiel de ressources ou de publier dans un canal de contenu.

Tâche 6 : Analyser les événements

Enfin, nous pouvons tester l'orchestration complète de l'expérience dans Oracle Content Management sans avoir à quitter l'interface Web d'Oracle Content Management. En fonction des modifications apportées au contenu ou au statut de publication, ou en cliquant simplement sur le bouton Tester dans l'onglet Sortant, les étapes suivantes sont effectuées :

  1. Oracle Content Management déclenche un build en appelant l'API de build Heroku à l'aide de l'en-tête et du corps spécifiés avec la demande POST sur l'adresse d'URL.

  2. Heroku reçoit la demande d'exécution d'un build qui utilise le code source (qui extrait du contenu d'Oracle Content Management).

  3. Heroku renvoie une réponse à Oracle Content Management au démarrage du build, fournissant ainsi un statut en attente et d'autres métadonnées.

  4. Une fois le build terminé, Heroku renvoie une autre réponse à Oracle Content Management concernant l'échec ou le succès du build avec des métadonnées supplémentaires.

Tous ces événements sont affichés dans l'onglet Events du panneau Properties. Voici un exemple de séquence d'événements numérotés 1, 2 et 3, dans l'ordre d'occurrence :

Cette image présente les événements de l'orchestration de l'expérience.

Comme indiqué, le premier événement (libellé 1) est le déclencheur d'Oracle Content Management à Heroku pour démarrer un build. Le deuxième événement (intitulé 2) est le webhook entrant renvoyé par Heroku indiquant à Oracle Content Management que le build a été démarré. L'événement final (intitulé 3) est l'événement de création réussi, également à partir du webhook entrant d'Heroku vers Oracle Content Management. Chacun de ces événements peut être analysé en détail en cliquant dessus dans l'onglet Events. Notez que tous les événements ont la même balise que "Heroku Endpoint API Build". Le premier événement (intitulé 1) est appelé, car c'était le nom que nous lui avons donné dans l'onglet Sortant. Les deuxième et troisième événements (libellés respectivement 2 et 3) sont balisés de la même manière puisque nous avons ajouté un jeton {{TARGET_IDENTIFIER}} aux demandes associées aux cibles.

Le contenu affiché sous chaque événement de l'onglet Evénements provient des paramètres de l'onglet Analyser. L'onglet Analyser vous permet d'extraire des informations des données traitées d'une réponse entrante et de les afficher dans l'onglet Evénements pour fournir des informations importantes aux éditeurs de contenu et aux contributeurs, par exemple lorsque leur contenu est enregistré, publié ou mis en ligne. Pour plus d'informations sur l'onglet Analyser, reportez-vous à la documentation Oracle Content Management.

Pour les événements affichés ci-dessus, les éléments suivants ont été spécifiés dans l'onglet Analyser :

Cette image présente l'analyse de l'orchestration de l'expérience.

L'orchestration complète de l'expérience

Cette section est facultative, mais présente l'ensemble du processus et des avantages liés à l'utilisation des fonctionnalités d'orchestration de l'expérience d'Oracle Content Management. Dans cette section, nous verrons une URL d'expérience en production, modifions le contenu, puis la publions et enfin le contenu publié sur un déploiement Heroku sans affecter l'URL d'expérience ni quitter Oracle Content Management.

Nous devons d'abord nous assurer que nous souhaitons afficher un aperçu des modifications en fonction du statut de publication des ressources dans OCEGettingStartedRepository, qui peut être défini dans l'onglet Sortant de l'expérience.

Tout d'abord, voici le site de l'URL de l'expérience, qui peut être défini dans la section Propriétés du site pour l'URL de l'expérience. Il s'agit de l'état actif actuel de votre site dont vous souhaitez voir les aperçus sans affecter cette production.

Cette image présente l'URL de l'expérience pour le blog.

Nous allons maintenant modifier le contenu et le publier sur le canal correspondant approprié. Pour cette section, mettons à jour l'actif de la page d'accueil du blog intitulé "Comment" et ajoutez-y les mots "Faire du café".

Recherchez l'immobilisation "Procédure" dans la barre de recherche et cliquez sur l'icône de modification.

Cette image montre l'équipement Comment.

Maintenant, modifions le contenu en ajoutant les mots "Faire du café" et enregistrez-le en haut à droite.

Cette image présente l'actif modifié Comment effectuer.

Publions ce contenu sur le canal approprié, qui doit déclencher la création appropriée pour l'aperçu.

Cette image montre l'onglet Publication.

Cette image présente l'enregistrement de publication dans le canal.

Nous pouvons vérifier le build déclenché en accédant à l'objet d'orchestration Expérience et en affichant l'onglet Evénements lors de l'analyse des événements.

Une fois le build terminé et réussi, nous pouvons vérifier que l'URL d'aperçu, que nous appelons " Heroku Endpoint API Build ", a ces mises à jour avec les mots " Make Coffee " après " How To ". Et nous pouvons voir que l'URL d'expérience précédente est toujours le même site.

Cette image présente l'URL d'aperçu du blog.

Conclusion et étapes suivantes

Dans ce tutoriel, nous avons déployé une application sur Heroku à partir d'une source GitHub en utilisant les fonctionnalités d'orchestration de l'expérience dans Oracle Content Management. Nous avons d'abord créé une application Heroku et déployé une source GitHub, comme l'exemple de référentiel de blog Vue, qui s'exécute à l'aide de Node.js. Nous avons ensuite créé une expérience Oracle Content Management et configuré les cookes Web sortants et les cookes Web entrants. Enfin, le processus d'orchestration de l'expérience est désormais configuré de sorte que, lors des modifications de contenu ou du statut de publication, ou en cliquant simplement sur le bouton Tester dans l'onglet Sortant, Oracle Content Management déclenche un build en appelant l'API de build Heroku à l'aide de l'en-tête et du corps spécifiés avec la demande POST sur le point d'extrémité d'URL. Les événements peuvent être analysés directement dans Oracle Content Management dans l'onglet Evénements. Nous avons également démontré le processus d'orchestration de l'expérience complète.

Les étapes suivantes de gestion du processus d'orchestration de l'expérience sont les suivantes :

  1. Visualiser les expériences connectées sans tête

  2. Partager l'objet d'expérience

Grâce à cela, nous pouvons désormais connecter des référentiels de contenu et des canaux de publication à des expériences sans tête déployées sur Heroku qui déclenchent automatiquement des déploiements en fonction des modifications de contenu ou du statut publié. Les fournisseurs de contenu peuvent tirer parti des avantages offerts par la gestion des ressources de référentiel. Ces avantages incluent notamment des outils performants qui permettent d'organiser, d'extraire, de traduire, de concevoir en groupe, d'approuver et de publier du contenu. Puis, sans quitter Oracle Content Management, ils peuvent prévisualiser leurs applications sans tête en contexte et avec du contenu. Les développeurs d'expérience peuvent utiliser les outils dont ils disposent et configurer des expériences sans tête pour qu'elles s'appuient automatiquement sur les modifications apportées au contenu dans les référentiels associés ou sur le statut de publication du contenu dans les canaux de publication associés afin de favoriser l'intégration continue/le déploiement continu.