Lo que necesitamos saber antes de comenzar con Open Commerce (antes llamado Reaction Commerce)

Como comenzar con Open Commerce (antes llamado Reaction Commerce), partes del proyecto y como lidiar con problemas.

Introducción

En resumen lo que Open Commerce es:

• Un backend/GraphQL API.
• Una aplicación de adminitración escrita usando el framework meteor.
• Un ejemplo de tienda (que ahora está basado en NextJS) y podemos usar como base o simplemente usar de modelo y re-escribir desde cero.

Lo ambientes están todos dockerizados y utilizan imagenes pre-armadas por el equipo de projecto con base NodeJS para cada módulo. Se puede cambiar todos estos ambientes a modo desarrollo usando el comando make.

Además de este núcleo del proyecto en la versión 3.x tenemos un Sistema de autenticación Hydra que integran (desarrollado por otro equipo). Pero en la versión 4.x (la actual) esto lo han dejado de lado reduciendo la complejidad del proyecto.

Adentrandonos en el proyecto

Estos son algunas de las cosas que me hubiera gustado que me cuenten antes de comenzar a trabar con Open Commerce (antes llamado Reaction Commerce):

• La idea detrás de la documentación actual es lograr tener andando en forma local en ambiente de desarrollo (fuertemente basado en Docker) en nuestra máquina. La idea detrás de esto es poder desarrollar plugins para Open Commerce.
• Para poder hacer esto el primer paso es clonar el repositorio git de reaction y luego correr make. Lo que tenemos que tener instalado para hacer esto es: make, Docker (ya sea Desktop o Engine) y docker-compose instalados localmente.
• Todo el sistema se “construye” usando make. En la documentación del proyecto podemos ver la lista de commandos, pero en escencia nos permitirá construir el ambiente (build), arrancarlo (start), detenerlo (stop), reconstruirlo (re-build) y correrlo en modo desarrollo. Existen más comandos, pero esos son los básicos.
• Los comandos más importantes serán: make, make start. Si no hay problemas, luego de correr los con estos comandos ya se podrá trabajar en forma local. Y para cerrar el sistema solo quedará correr: make stop.
• Si hay problemas, vamos a requerir algunos conocimientos de Docker y familiarizarnos un poco con la arquitectura de Open Commerce. A pesar de tener todo automatizado con make, se puede arrancar y parar sus partes individualmente. En la próxima sección de este articulo voy a compartir algunas reglas generales y herramientas para poder lidiar con problemas.
• El sistema tiene muchas partes que vienen pre-configuradas. No solo tenemos distintas partes dentro del proyecto, si no que tenemos otros proyectos que conviven orquestados dentro del mismo. La documentación de MailChip sobre Open Commerce Comienzo Rápido es de gran ayuda cuando estamos dando los primeros pasos.

Lo que deberíamos tener corriendo luego de que make termina de ejecutar es una cantidad de instancias de docker corriendo. Si corremos docker ps -a veremos los nombres de las imagenes (IMAGE names), para hacerlo un poco más genérico omitiré las versiones:

• reactioncommerce/example-storefront: Este es el docker que corre la versión de la tienda de compra que verá el comprador al visitar el sitio.
• reactioncommerce/admin: Este es el sitio de administración del sitio que vemos (backend del storefront). Es el que permite administrar a la tienda. Se pueden crear productos, manejar órdenes, etc…
• reactioncommerce/reaction: Este es el servidor GraphQL API que le da información tanto al frontend (storefront), como al backend (admin).
• mongo: Necesitamos este servidor de base de datos para el GraphQL API server (reaction).

En la versión 3.x del sistema además se crean:

• reactioncommerce/identity: Junto con Hydra esto permite a los usuarios (tanto compradores como administradores) autenticarse.
• oryd/hydra: Esto es un proyecto separado que ha sido integrado a Open Commerce y trabaja junto con el módulo de identidad (identity) para permitir a los usuarios autenticarse.
• postgres: Esto es un servidor de base de datos que necesita Hydra para poder correr.

Estos módulos ya no son necesarios en la versión 4.x del proyecto, lo que ha sido un gran avance y reducido mucho la complejidad del proyecto.

Una vez que tenemos el sistema corriendo para poder ver sus diferentes partes deberemos visitar:

• localhost:4000 para poder ver el sitio que usan los clientes (storefront).
• En localhost:4080 vamos a poder acceder al sistema de administración (admin).
• Y si nos interesa en localhost:3000/graphql podremos interactuar directamente con GraphQL.

Existen otros puertos y sistemas corriendo, pero estos son los realmente interesantes.

Lidiando con problemas

Con tantas partes móbiles hay muchas cosas que pueden salir mal, así que voy a enfocar esta sección en conseguir información útil de los containers de docker.

Lo más importante es tener todos los contenedores corriendo, si alguna no logra levantar debermos trabajar con ese docker manualmente. Si bien make orquesta todo, cada una de las partes es un sistema separado y puede trabarse con ellos individualmente.

Cada contenedor tiene un directorio dentro del repositorio clonado. Por ejemplo el contenedor reactioncommerce/admin corresponde al directorio reaction-admin. Dentro de este directorio tendremos el archivo docker-compose.yml que describe al contenedor. Esto significa que si nos movemos a este directorio con cd reaction-admin podremos correr los siguientes comandos:

• bin/setup: Este es un script de bash que realiza todas las tareas necesarios para lograr que el contenedor corra.
• docker-compose up -d: En definitiva esto termina haciendo lo mismo que el comando anterior, pero lo hace dentro del ambiente del contenedor y no nos permite ver todos los errores.
• docker-compose down: Este comando es útil para parar el contenedor manualmente.

Si bien existen de manera separada, todos los comandos estan integrados en el sistema make de reaction. Pero a veces es conveniente realizar estas tareas de manera separada:

• docker-compose up: Esto también arranca al contenedor, pero muestra errores y si es la primera vez también lo “construye” (se baja todo lo necesario para correr el contenedor docker).
• docker-compose logs -f: Este comando permite ver todos los archivos log (historial/errores) del contenedor. Esto es útil cuando estamos intentando entender algún problema.

En ambos casos lo que veremos es la consola de contenedor. Esto nos proveé mucha información de ayuda para entender los errores. Y si los combinamos con los 3 comandos anteriores nos permitira entender que pasa con un particular subsistema.

Actualmente no se está manteniendo la documentación original y muchas páginas apuntaran directamente al sitio de Mailchimp Open Commerce con su ajustado resumen de lo que se puede hacer. Existe el proyecto reaction-docs @ github y correrlo localmente:

git clone git@github.com:reactioncommerce/reaction-docs.git
cd reaction-docs
bin/setup
docker-compose up

Si luego visitamos localhost:4242 podremos tener mucha información adicional sobre la platforma. Pero hay que tener cuidado con esta documentación ya que está desactualizada. El equipo entre las versiones 3.x y 4.x hizo cambios importantes, así que lamentablemente muchas veces los archivos MarkDown dentro del repositorio o el código fuente serán mejores que la documentación.

La comunidad además tiene un canal discord donde hay actividad y se puede pedir ayuda.

En este articulo se presenta las particularidades de un ambiente de desarrollo, pero para un ambiente de producción será necesario una configuración diferente. La comunidad proveé una receta Traefik que puede ayudar (al menos con un ambiente QA) y discutiremos en un articulo futuro.

Espero que esta entrada del blog los pueda ayudar con sus primeros pasos.