Despliegue de aplicaciones en Heroku con Experience Orchestration en Oracle Content Management

Introducción

Heroku es una plataforma en la nube que permite crear, entregar, supervisar y ampliar aplicaciones.

El despliegue de una aplicación en Heroku es una operación sencilla que solo requiere unos pocos pasos sencillos para las aplicaciones básicas, pero también puede soportar muchos ajustes avanzados para escenarios más complejos.

En este tutorial, desplegaremos una aplicación en Heroku desde un origen de GitHub utilizando las funciones de orquestación de experiencias de Oracle Content Management. Oracle Content Management proporciona una forma de conectar repositorios de contenido y publicar canales a experiencias sin cabecera desarrolladas y gestionadas fuera de Oracle Content Management y disparar automáticamente despliegues basados en cambios de contenido o estados publicados.

El tutorial consta de los siguientes pasos:

1. Crear una aplicación Heroku
2. Crear una experiencia de Oracle Content Management
3. Configuración de webhooks salientes
4. Configuración de webhooks entrantes
5. Opcionalmente, agregue webhooks salientes/entrantes adicionales para la vista previa del contenido
6. Analizar los eventos

Requisitos

Antes de continuar con este tutorial, le recomendamos que lea primero la siguiente información:

• Conexión a experiencias sin cabecera

Para seguir este tutorial, necesitará:

• una suscripción a Oracle Content Management
• una cuenta de Oracle Content Management con el rol de administrador de contenido
• una cuenta de Heroku con el rol Miembro o Administrador
• una cuenta de GitHub con código fuente

Tarea 1: Crear una aplicación de Heroku

Si aún no tiene una instancia de Oracle Content Management, consulte Inicio rápido para aprender a registrarse en Oracle Cloud, aprovisionar una instancia de Oracle Content Management y configurar Oracle Content Management como un CMS sin cabecera.

Si aún no tiene una cuenta de Heroku, tendrá que crear una cuenta de Heroku. El nivel gratuito tiene privilegios suficientes para desplegar la mayoría de aplicaciones de Heroku simples.

Si aún no tienes una cuenta de GitHub, necesitarás crear una cuenta GitHub. Una cuenta gratuita básica es todo lo que necesitas para poner tu código fuente. El código fuente puede ser un repositorio público o privado.

Una vez configurados todos ellos, conectaremos Heroku a GitHub y desplegamos una aplicación:

1. Inicie sesión en Heroku y seleccione Personal o Equipo en la parte superior izquierda según su caso de uso.

   

2. Haga clic en Nuevo en el menú desplegable de la parte superior derecha y seleccione Crear nueva aplicación.

   

3. Asigne a su aplicación un nombre y haga clic en Crear aplicación.

   

4. Abra el separador Desplegar y conéctese a GitHub buscando en el repositorio y seleccione el que desea desplegar. Si desea desplegar la última versión de la aplicación, este valor se puede dejar como 'main' (que es el valor por defecto). Si es la primera vez que crea un sitio de este proveedor, se le pedirá que otorgue permiso a Heroku para acceder a sus repositorios. Siga las indicaciones para permitir esto.

   

   

5. Por primera vez, deberá hacer clic en Desplegar rama en la sección Despliegue manual. Si desea activar despliegues automáticos, actívelos en la sección Despliegues automáticos.

   

Tenga en cuenta las consideraciones siguientes:

• Si necesita definir variables de entorno antes de ejecutar la creación, asegúrese de hacerlo en el archivo .env.

• Asegúrese de que todos los archivos necesarios se encuentran en el repositorio de GitHub, prestando especial atención a los archivos .env y .gitignore.

• El archivo Package.json debe contener entradas install, build y serve en los scripts de las aplicaciones Node.js.

• Con la API Heroku Connect se pueden utilizar otras formas de conectarse con Heroku que no utilice GitHub. Puede encontrar más detalles en el Centro de desarrollo de Heroku.

• Si el despliegue falla, lea los logs de creación y aplicación con cuidado para detectar cualquier error.

• Consulte el Centro de desarrollo de Heroku para obtener más información sobre implementación de Node.js y resolución de problemas de despliegues de Node.js.

• Otros entornos de tiempo de ejecución también cuentan con soporte de idioma en Heroku. Consulte Heroku Dev Center para obtener más información.

Repositorio de Vue de muestra para el despliegue de Heroku

Esta sección es opcional, pero proporciona un repositorio de ejemplo de blog Vue que se puede desplegar fácilmente en Heroku. Puede encontrar el repositorio en GitHub.

Hay un tutorial disponible sobre cómo configurar el ejemplo de blog Vue en Oracle Help Center, incluido un recorrido virtual por el vídeo. Puede que sea necesario configurar este ejemplo en el sistema, como cambiar el archivo .env y cargar datos en el servidor, que se muestra en el tutorial.

Puedes bifurcar este repositorio en tu cuenta accediendo al repositorio de GitHub y haciendo clic en "fork".

Al forzar un repositorio se crea una copia del repositorio. Aquí, forzar un repositorio le permite experimentar libremente con los cambios sin afectar el proyecto original, pero no se necesitan cambios para poder desplegar esta aplicación en Heroku.

Una vez que haya bifurcado este proyecto, podrá seguir adelante y crear su primer despliegue de ejemplo, como se ha descrito anteriormente.

Solucionar posibles errores de CORS para tu aplicación Heroku

Esta sección le ayudará a corregir cualquier error de CORS (uso compartido de recursos de origen cruzado) que pueda existir en la aplicación. CORS es un estándar que permite a un servidor relajar la política de mismo origen, por lo que si la ubicación de dónde se sirve la aplicación y el origen del recurso que se solicita son diferentes, entonces la política de mismo origen del explorador web entra en vigor y CORS es necesario para que se realice la solicitud.

Puede activarla en la interfaz web de Oracle Content Management accediendo a Sistema y, a continuación, a Seguridad. Agregue la URL de la aplicación Heroku a Orígenes CORS de canal frontal y, a continuación, haga clic en Guardar.

Nota: Según la política de mismo origen, dos URL tienen el mismo origen si comparten exactamente el mismo protocolo, dominio y puerto. Esto significa que puede que necesite agregar URL http y https en esta sección.

Tarea 2: Creación de una experiencia de Oracle Content Management

En la tarea anterior, conectamos Heroku a GitHub. Ahora vamos a crear un objeto de experiencia de Oracle Content Management, que se conectará con Heroku más adelante.

Para crear un objeto de experiencia en Oracle Content Management:

1. Conéctese a la interfaz web de Oracle Content Management como administrador.

2. Haga clic en Experiencias en el panel de navegación izquierdo y, a continuación, haga clic en Crear en la parte superior derecha.

   

3. Introduzca la información necesaria y haga clic en Crear cuando termine. Puede encontrar más información en la documentación de Oracle Content Management.

   

Tarea 3: configuración de webhooks salientes

A continuación, vamos a configurar el webhook saliente para el objeto de experiencia de Oracle Content Management recién creado. El webhook saliente está diseñado para disparar automáticamente despliegues de Oracle Content Management en Heroku según los cambios de contenido o el estado publicado.

Para configurar los webhooks salientes:

1. Conéctese a la interfaz web de Oracle Content Management como administrador.

2. Haga clic en Experiencias en el panel de navegación izquierdo.

3. Seleccione la experiencia que desea configurar y, a continuación, abra el panel Propiedades.

   

4. En el panel Propiedades, abra el separador Saliente.

   

5. Configure el nombre del destino, el método (GET o POST), el punto final de URL y el disparador de la solicitud.

   • Nombre de destino: puede asignar al destino el nombre que desee. Oracle Content Management proporcionará un TARGET_IDENTIFIER único para este destino.

   • Método: especifique GET o POST en la solicitud mediante el menú desplegable. Para Heroku, queremos hacer una solicitud POST para disparar una creación.

   • Punto final de URL: este es el punto final de API. Para Heroku, utilizaremos el punto final https://api.heroku.com/apps/NAME-OF-YOUR-HEROKU-APP/builds, donde NAME-OF-YOUR-HEROKU-APP se debe sustituir en consecuencia.

   • Disparador de solicitud: se encuentra en el separador Contenido, donde puede especificar un disparador basado en un evento específico. En el siguiente ejemplo, se disparará una creación basándose en un cambio en el repositorio de activos denominado OCEGettingStartedRepository, que representa el canal de blog en Oracle Content Management.

   

6. Configure las cabeceras. Necesitará tres cabeceras: Autorización, Aceptar y Tipo de Contenido. Estos se documentan en la documentación de Heroku.

   • Autorización: token de autorización que necesita obtener de Heroku. Solo los usuarios autorizados pueden crear compilaciones desde Heroku, y este token es necesario para la autenticación para utilizar la API de Heroku. Puede ver su clave de API de Heroku en Configuración de cuenta > Clave de API > Revelar.

   • Aceptar: esta es la cabecera Aceptar: application/vnd.heroku+json; version=3. Tenga en cuenta que debe utilizar la versión 3 de la API de compilación de Heroku para que funcione.

   • Tipo de Contenido: será la cabecera Content-Type: application/json.

   

7. Configure el cuerpo. Necesitarás un blob de origen con una URL y una versión opcional con formato de objeto JSON como se muestra a continuación. El blob de origen es donde se encuentra su código de origen para el despliegue. El objeto JSON para el cuerpo debe ser:

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

   URL

   La URL que se va a utilizar es la ubicación en la que se ha descargado un archivo tar comprimido del código de origen para la creación. Lo conseguiremos a través de la API de GitHub.

   Tenga en cuenta que hay una diferencia en la URL para repositorios públicos frente a privados en GitHub. Consulte la documentación de Heroku para obtener más información.

   Para los repositorios públicos, su URL debe ser:

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

   Para repositorios privados, su URL debe ser:

   https://user:[e-mail]/repos/<username>/<repo name>/tarball/<branch>

   <username> es su nombre de usuario de GitHub, <repo name> es el enlace amigable del repositorio GitHub y <branch> es el nombre de la rama (normalmente 'main' o 'master'). A continuación se muestra un ejemplo de repositorio público.

   Para repositorios privados, debe cambiar la sección user:token para la URL de blob de origen del repositorio privado. La parte user se puede sustituir por el mismo nombre de usuario que antes y token se debe sustituir por un token de acceso personal de GitHub con el ámbito adecuado. Para generar este token, siga los pasos descritos en la documentación de GitHub. Preste especial atención a la fecha de caducidad de este token (normalmente no desea definirlo para que caduque) y solo debe otorgar a este token acceso "repo", que proporciona control total sobre los repositorios privados.

   versión

   El parámetro de versión no es necesario y no se utiliza al descargar y crear el código de origen. Es simplemente un fragmento de metadatos que puede utilizar opcionalmente para realizar un seguimiento de la versión del código fuente en la creación de qué enlace amigable (slug).

   En nuestro caso, agregaremos "{{TARGET_IDENTIFIER}}" como parámetro de versión. Oracle Content Management colocará TARGET_IDENTIFIER como ID visto junto al nombre de destino en el cuerpo de la solicitud. Cuando se envíe esto a Heroku, se le devolverá a través del webhook entrante una vez que esté configurado. En esta respuesta de Heroku sobre la creación, Oracle Content Management recibirá la carga útil y evaluará si ese ID de destino existe. Si lo hace, la carga útil está asociada al destino saliente de Oracle Content Management; de lo contrario, se considera "Desconocido". Puede encontrar más información sobre los ID de destino en la documentación de Oracle Content Management.

   

8. Haga clic en Apply (Aplicar) en la parte superior derecha para guardar la configuración.

9. Opcionalmente, haga clic en Probar junto al punto final de API para probar un disparador de esta creación como si el contenido o el estado publicado cambiaran en el canal seleccionado.

Nota: En la documentación de Oracle Content Management se pueden encontrar detalles adicionales sobre la configuración del webhook saliente en Oracle Content Management.

Tarea 4: Configurar webhooks entrantes

A continuación, configuraremos el webhook entrante de Heroku a Oracle Content Management para el objeto de experiencia recién creado. El webhook entrante está diseñado para devolver información sobre la creación y su estado a Oracle Content Management sin salir de Oracle Content Management. Los resultados se pueden ver en el separador Eventos, donde se puede encontrar más información al analizar los eventos.

Para configurar los webhooks entrantes:

1. Conéctese a la interfaz web de Oracle Content Management como administrador.

2. Haga clic en Experiencias en el panel de navegación izquierdo.

3. Seleccione la experiencia que desea configurar y, a continuación, abra el panel Propiedades.

   

4. En el panel Propiedades, abra el separador Entrante. Copie la URL del webhook, que colocaremos en Heroku.

   

5. Vuelva a conectarse a Heroku y busque la aplicación. En la parte superior derecha, haga clic en Más y, a continuación, en Ver webhooks.

   

6. Haga clic en Crear webhook en el centro de la pantalla.

   

7. En el cuadro de diálogo New Webhook, proporcione la información del nuevo webhook. Cualquier nombre es correcto, la URL de carga útil debe ser la copiada de Oracle Content Management y no se necesita ningún secreto. Para los tipos de eventos, asegúrese de que solo se seleccione 'api:build'.

   

8. Haga clic en Agregar webhook cuando termine.

Tarea 5 (opcional): agregar webhooks salientes y entrantes adicionales para Content Preview

Las API de REST están disponibles en Oracle Content Management para la entrega y gestión de contenido, así como para conversaciones, documentos, usuarios y grupos. Para la integración con Heroku, puede ser útil tener dos despliegues separados en diferentes aplicaciones de Heroku utilizando la misma experiencia para la vista previa del contenido y la entrega de contenido, de modo que se pueda obtener una vista previa de los cambios no publicados en un activo en una aplicación sin afectar la creación de entrega de producción. En esta sección opcional, veremos cómo utilizar un segundo destino en la experiencia para disparar despliegues de vista previa independientemente de los despliegues de producción.

El primer paso es crear un total de dos aplicaciones de Heroku separadas, donde una aplicación de Heroku utilizará el contenido de la vista previa y el otro el contenido de la entrega. Puede crear una aplicación Heroku siguiendo las instrucciones de la tarea 1.

Una vez configurado, deberá configurar ambos destinos salientes. Puede agregar un segundo destino haciendo clic en Agregar Destino en la parte inferior. Siga los pasos de la tarea 3 para crear un webhook saliente. Tenga en cuenta que debe haber dos diferencias principales entre ambos webhooks salientes:

1. La API de entrega de contenido se debe disparar en función de una publicación en el canal de contenido y la API de vista previa de contenido se debe disparar en función de un cambio en el repositorio de contenido.

2. El cuerpo del webhook saliente debe estar vinculado al código adecuado que utilice la API de entrega de contenido o la API de vista previa de contenido. Esto requerirá que el código de vista previa y el código de entrega se alojen en dos repositorios independientes de GitHub.

   

Nota: Para obtener más información sobre la configuración de la API de vista previa en Oracle Content Management, consulte Uso de API de vista previa en sitios de Oracle Content Management sin cabecera.

El último paso consiste en configurar los webhooks entrantes de cada aplicación de Heroku, que se pueden realizar siguiendo los pasos de la tarea 4 para cada una de las aplicaciones. Ambas aplicaciones de Heroku compartirán la misma URL de webhook entrante proporcionada por Oracle Content Management.

Un problema importante a tener en cuenta es que Heroku limita el número de compilaciones simultáneas por cuenta. Heroku solo permite que las cuentas verificadas ejecuten compilaciones de múltiples aplicaciones en una cuenta simultáneamente, lo que requiere un pago adicional a Heroku. Si utiliza la versión gratuita de Heroku integrada con la función de orquestación de experiencias de Oracle Content Management en dos aplicaciones de Heroku en la misma cuenta, puede que tenga que esperar a que finalicen las compilaciones antes de realizar otro cambio en un repositorio de activos o publicar en un canal de contenido.

Tarea 6: Análisis de los eventos

Por último, podemos probar la orquestación de experiencias completas en Oracle Content Management sin tener que salir de la interfaz web de Oracle Content Management. En función de los cambios en el contenido o el estado de publicación, o simplemente haciendo clic en el botón Probar del separador Saliente, se realizarán los siguientes pasos:

1. Oracle Content Management dispara una compilación llamando a la API de compilación de Heroku mediante la cabecera y el cuerpo especificados con la solicitud POST en el punto final de URL.

2. Heroku recibe la solicitud para realizar una creación, que utiliza el código fuente (que extrae contenido de Oracle Content Management).

3. Heroku devuelve una respuesta a Oracle Content Management cuando se inicia la creación, proporcionando un estado pendiente y otros metadatos.

4. Cuando finaliza la creación, Heroku devuelve otra respuesta a Oracle Content Management sobre el fallo de la creación o el éxito con metadatos adicionales.

Todos estos eventos se muestran en el separador Eventos del panel Propiedades. A continuación se muestra una secuencia de ejemplo de los eventos numerados 1, 2 y 3, en orden de aparición:

Como se muestra, el primer evento (con la etiqueta 1) es el disparador de Oracle Content Management a Heroku para iniciar una creación. El segundo evento (con la etiqueta 2) es el webhook entrante de Heroku diciendo a Oracle Content Management que se ha iniciado la creación. El evento final (con la etiqueta 3) es el evento de creación correcto, también desde el webhook entrante de Heroku a Oracle Content Management. Cada uno de estos eventos se puede analizar en detalle haciendo clic en ellos en el separador Events. Observe cómo todos los eventos tienen la misma etiqueta denominada "Heroku Endpoint API Build". Se llama al primer evento (con la etiqueta 1), ya que ese fue el nombre que le entregamos en la ficha Saliente. Los eventos segundo y tercero (etiquetados 2 y 3, respectivamente) se etiquetan de la misma forma, ya que agregamos un token {{TARGET_IDENTIFIER}} a las solicitudes asociadas con destinos.

El contenido que se muestra debajo de cada evento del separador Eventos procede de la configuración del separador Analizar. El separador Analizar permite extraer información de una carga útil de respuesta entrante y mostrarla en el separador Eventos para proporcionar información importante para los editores y contribuyentes de contenido, como cuándo se guarda, se publica o se activa su contenido. Puede encontrar información adicional sobre el separador Analizar en la documentación de Oracle Content Management.

Para los eventos mostrados anteriormente, se especificó lo siguiente en el separador Analizar:

La orquestación de experiencia completa

Esta sección es opcional, pero muestra todo el proceso y las ventajas de utilizar las funciones de orquestación de experiencias de Oracle Content Management. En esta sección, veremos una URL de experiencia en producción, realizar un cambio en el contenido, luego publicarlo y, finalmente, ver el contenido publicado en un despliegue de Heroku sin afectar la URL de experiencia ni salir de Oracle Content Management.

Primero debemos asegurarnos de que deseamos ver los cambios de vista previa basados en el estado de publicación de los activos en OCEGettingStartedRepository, que se puede definir en el separador Saliente de la experiencia.

En primer lugar, este es el sitio URL de experiencia, que se puede definir en la sección Propiedades del sitio para la URL de experiencia. Este es el estado activo actual de su sitio del que desea ver las vistas previas sin afectar a esta producción.

Ahora, crearemos un cambio en el contenido y publicaremos ese contenido en el canal correspondiente correcto. Para esta sección, actualicemos el activo de la página de inicio del blog denominada 'Cómo' y le agregamos las palabras 'Hacer café'.

Busque el activo de instrucciones en la barra de búsqueda y haga clic en el icono de edición.

Ahora, cambiemos el contenido añadiendo las palabras 'Hacer café' y guardarlo en la parte superior derecha.

Publicemos ese contenido en el canal correcto, que debería disparar la creación adecuada para la vista previa.

Podemos verificar la creación disparada accediendo al objeto de orquestación de experiencias y viendo el separador Eventos al analizar los eventos.

Una vez finalizada y exitosa la creación, podemos verificar que la URL de vista previa, que llamamos 'Heroku Endpoint API Build', tiene esas actualizaciones con las palabras 'Make Coffee' después de 'How To'. Y podemos ver que la URL de experiencia anterior sigue siendo el mismo sitio.

Conclusión y siguientes pasos

En este tutorial, hemos desplegado una aplicación en Heroku desde un origen de GitHub utilizando las funciones de orquestación de experiencias de Oracle Content Management. Primero creamos una aplicación Heroku y desplegamos un origen de GitHub, como el repositorio de blogs de Vue de ejemplo, que se ejecuta con Node.js. A continuación, creamos una experiencia de Oracle Content Management y configuramos los webhooks salientes y los webhooks entrantes. Por último, el proceso de orquestación de experiencias ahora está configurado de modo que en los cambios en el contenido o el estado de publicación, o simplemente haciendo clic en el botón Probar del separador Saliente, Oracle Content Management disparará una creación llamando a la API de creación de Heroku mediante la cabecera y el cuerpo especificados con la solicitud POST en el punto final de URL. Los eventos se pueden analizar directamente en Oracle Content Management en el separador Events y también demostramos el proceso completo de orquestación de experiencias.

Los siguientes pasos para gestionar el proceso de orquestación de experiencias son:

1. Ver las experiencias sin cabecera conectadas

2. Comparta el objeto de experiencia

Con esto, ahora podemos conectar repositorios de contenido y publicar canales a experiencias sin cabecera desplegadas en Heroku que disparan automáticamente despliegues basados en cambios de contenido o estado publicado. Los proveedores de contenido pueden aprovechar las ventajas de la gestión de activos de repositorios, como herramientas potentes para organizar, recuperar, traducir, aprobar, publicar y colaborar en contenido. A continuación, sin salir de Oracle Content Management, pueden obtener una vista previa de sus aplicaciones sin cabecera en contexto y con contenido. Los desarrolladores de experiencias pueden trabajar con herramientas que disponen y configurar experiencias sin supervisión para crearlas automáticamente en función de los cambios en el contenido de los repositorios asociados o publicar el estado del contenido en los canales de publicación asociados a fin de fomentar la integración continua/despliegue continuo (CI/CD).

---

Título e Información de Copyright

Despliegue de aplicaciones en Heroku con Experience Orchestration en Oracle Content Management

F52234-02

Junio 2022

Copyright © 2021, 2022, Oracle and/or its affiliates.

Autor Principal: Oracle Corporation