Broadleaf Microservices
  • v1.0.0-latest-prod

Backend Flex Package APIs (DEPRECATED as of 1.8.2-GA)

Note
 Deprecation Notice: these instructions are applicable to older project structures not generated using Broadleaf Initializr and Manifest. We recommend starting new projects using Broadleaf Initializr.

System Configuration

Important
 The following assumes you have obtained credentials outlined in the guide: Getting Started Locally.

Java

You will need Java 11 installed on your machine.

e.g. MacOS QuickStart using Homebrew

brew tap AdoptOpenJDK/openjdk
brew cask install adoptopenjdk11

Docker

You will need to have Docker Engine & Docker Compose installed locally

Tip

Docker Desktop for both Mac and Windows already includes compose along with other docker apps.

Once you have docker installed, you will want to authenticate with Broadleaf’s docker registry.

Type the following into your CLI:

docker login repository.broadleafcommerce.com:5001

When prompted, type in the username and password you were given.

Important

You’ll also want to configure Docker settings to use appropriate resources. A good rule of thumb is to allow Docker to consume around 3/4 of your system resources as necessary.

At a minimum, you will want to allocate at least 2 CPUs and 4-6 GB Memory

Ideally for a developer machine, you will want to allocate something like: 6 CPUs, 8 GB Memory, 4 GB Swap.

Maven

You’ll need to either have Maven 3.5 or later installed locally, utilize the ./mvnw wrapper included with the starter project, or leverage the maven facilities that come with your IDE.

Regardless of how you invoke Maven, you’ll need to configure authentication to Broadleaf’s Nexus repository in order to build the project and pull down Broadleaf artifacts. You can specify these credentials in a file called settings.xml.

settings.xml

Create a file called settings.xml with the following contents making sure to replace the credentials with the specific Nexus credentials you were given.

<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
    xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <servers>
    <server>
      <id>broadleaf-microservices</id>
      <username>username_here</username>
      <password>password_here</password>
    </server>
  </servers>
</settings>

If you’re using Maven via your IDE, you should make sure your User Settings File is pointing to the correct settings.xml file which contains the Broadleaf nexus credentials. For example:

  1. Create a folder called .m2 in your home directory and (i.e. ~/.m2/settings.xml) move the settings.xml file into that directory

  2. In IntelliJ: verify that Preferences > Build, Execution, Deployment > Build Tools > Maven > User Settings File is pointed to the correct settings.xml file

If you are using the ./mvnw wrapper, you’re going to need to inform the executable of Broadleaf’s nexus credentials.

Either:

  • Move the settings.xml file created above into the wrapper folder (there will be a .mvn/wrapper direcory in the root of the starter project)

  • Create a folder called .m2 in your home directory and (i.e. ~/.m2/settings.xml) move the settings.xml file into that directory

Maven Installed Locally

If you already have Maven installed locally, you can create a settings.xml file in the .m2 subdirectory of your a user’s home directory.

  • Create a folder called .m2 in your home directory and (i.e. ~/.m2/settings.xml) move the settings.xml file into that directory

Tip

More info about authenticating with private repositories can be found here and here

Host File

Certain Flex Package local configurations require an update to your /etc/hosts file. For example, with the Min Flex Package composition, the indexer service will be deployed as a separate Docker image from the search service that is running outside a docker container. In this case, it is required that you add an entry to your hosts file, e.g. /etc/hosts, with a mapping between 127.0.0.1 and localsolr:

127.0.0.1 localsolr

Project Structure Overview

This Spring Boot starter project is structured in a manner that is meant to demonstrate various Flex Package compositions of the framework.

Note
 A FlexPackage is a configuration and packaging concept for Broadleaf allowing multiple microservices to exist in a single JVM runtime under a single Spring instance. This means that beans are for the most part shared, allowing increased economy in resource outlay. The FlexPackage performs smart routing of data and persistence to the correct, separate backing datastore for each contained microservice.

You’ll notice this high level folder structure:

Starter/
├── flexpackages/
│   ├── balanced
|   |   ├── browse
|   |   ├── cart
|   |   ├── processing
|   |   ├── supporting
|   |   └── docker
│   ├── common
|   |   └── docker
│   ├── granular
|   |   └── docker
│   └── min
|       └── docker
└── services/
    ├── adminnav
    ├── adminuser
    ├── asset
    ├── campaign
    ├── cart
    └── ...

flexpackages/

  • min emits a single FlexPackage consisting of almost all the core commerce services bundled together as part of the maven lifecycle. This would represent the most minimal deployment footprint. Note that with min , the indexer is deployed as a separate service.

  • balanced consists of 4 FlexPackages (browse, cart, processing, and supporting).

  • granular doesn’t emit a java artifact itself - rather - it is a holding area for the granular docker builds that refer to the individual services defined in the project services directory. This configuration would represent deploying each service individually.

Tip
 The min Flex Package Composition is recommended as a good default starting point for most local development use cases, whereas the balanced Flex Package Composition is recommended for production environments.

services/

  • They reflect the broadleaf services

  • Each leverages a BLC dependency as a starting point

  • This is where customizations & new code should be added

  • Customizations should be mindful of the type of service (resource vs orchestration) & the bounded context

  • We recommend that these projects reflect the same package structure as the BLC dependency

  • See flex package poms to understand how these services are organized within each application

Each of the maven subprojects here is meant to reflect the Broadleaf services that you intend to include in your project. Each of these projects depends on a specific Broadleaf service, providing a starting point for your version of that service. For example, the cart service depends on com.broadleafcommerce.microservices:broadleaf-cart-services.

From there, the cart subproject is where you’ll want to provide any customizations (extensions/overrides or new code) for your cart representations. As you make customizations, there are a few things to keep in mind:

  • Be mindful of the type of service that you’re customizing.

    • If you’re customizing an orchestration service like CartOperationServices, then you likely should not introduce a persistence component. Instead, you should pass off to a resource-tier service for persistence. A good example of this is the interaction between CartOperationServices and CartServices, where CartOperationServices coordinates actions against the cart, but it passes off to CartServices for querying/persisting the cart.

    • If you’re customizing a resource-tier service, then you likely should not introduce a component that directly communicates with another resource-tier service or add another resource-tier service as a dependency. While this technically can be done, we recommend maintaining the bounded contexts of the resource-tier services so that they remain decoupled. This will help to enable you to reorganize your flex packages in the future if needed.

Each of these service subprojects produce a single .jar during the maven lifecycle, which is then pulled into the various Flex Package compositions, adding that service to a specific Spring Boot application.

Important Pieces

For each of the Flex Package examples, there are some key components to take note of:

  1. docker-compose.yml - this is the main entrypoint for initializing one of the Flex Package compositions. This defines some supporting services that are required to run the full scope of these examples. See this FAQ: "What is the purpose for all of these supporting docker services?" to get a description about each of these images

  2. pom.xml - (except for granular) this defines which microservice dependencies that will be utilized for that Flex Package (e.g. catalog, catalog browse, pricing, offers, etc…​ for the browse Flex Package)

  3. src/main/resources/application-default.yml - this file configures a few default properties needed for that particular Flex Package composition (including database configuration and initialization parameters)

Building & Running the Project via the Command Line

The following section will walk through getting the backend APIs running locally via the command line. If you will be actively developing APIs and extensions on top of the framework, it is recommended that you follow the IntelliJ Setup instructions to take advantage of benefits provided by an IDE development workflow.

Building

Note

For the sake of simplicity, the following instructions will walk through building and starting the min flex package

Now that all of the pre-requisites are installed, let’s build and run the project!

Navigate to the root folder of the starter project (i.e. the folder that contains the main pom.xml file) of where you downloaded/un-zipped or cloned the project. In the root of this project run the following to build:

# If using Maven Wrapper
./mvnw clean install -s .mvn/wrapper/settings.xml

# If you have Maven installed
mvn clean install
Note

It may take some time during the initial installation as the process needs to download all required dependencies. All subsequent builds should go much faster.

Also note that running a build at the root of this project will build ALL Flex Package examples (balanced, min, and granular)
Tip

You can enable running the example tests in this project by running mvn clean install -DskipTests=false

Starting up Supporting Utility Services

Before you start up all the APIs, you’ll need to first start up a few supporting services that are required for this example. These services are provided via docker images and can be run and started from the command line by navigating to the root of this project and running:

cd flexpackages/min/docker
docker-compose up -d && ./check-services-status.sh
Note

The above command starts the creation process of all the supporting services using docker-compose. We’ve also included a script to "tail" all the relevant containers and verify successful startup.

./check-services-status.sh

This shell script will wait (for a period of time) to verify that all supporting services have started up before exiting and should produce something like below when everything is up and running:

zk - Container Started
openapi-ui - Container Started
auth - Container Started
commercegateway - Container Started
admingateway - Container Started
commerceweb - Container Started
adminweb - Container Started
localsolr - Container Started
database - Container Started
localkafka - Container Started
adminweb - Service Ready
openapi-ui - Service Ready
commerceweb - Service Ready
localsolr - Service Ready
zk - Service Ready
auth - Service Ready
commercegateway - Service Ready
admingateway - Service Ready
localkafka - Service Ready

Running Backend APIs

Starting the min Spring Boot Application

Next, you will want to start up the core backend commerce APIs.

Important

You’ll want to make sure that all your docker images have started up successfully before running this command, otherwise you may get startup errors trying to connect to a service that may not have finished completing.

You can start the APIs using the maven spring boot plugin using this command:

cd flexpackages/min
mvn spring-boot:run
Note

If you are running into issues running via the maven spring-boot plugin on Windows due to "large classpath/filename too long" errors. You can also start the application as an executable jar.

java -jar -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8004 flexpackages/min/target/demo-min-application.jar
Note

Depending on your configured system resources, this may take some time to fully start up.

In general, the sequence of events that you will encounter include:

  1. Tomcat initialization

  2. SQL changelog execution

  3. SOLR and Zookeeper connection initialization

  4. Spring bean initialization

  5. Kafka Pub/Sub messaging channel and consumer initialization

  6. Tomcat started on port(s): 8447 (https) with context path ''

  7. Started Demo Application

Starting the indexer Spring Boot Application

Next, you will want to start up the indexer service using the maven spring boot plugin with this command:

cd services/indexer
mvn spring-boot:run -Dspring-boot.run.profiles=localdev,min

Done

That’s it! Once you’ve verified that the supporting services and backend APIs are running, you can visit the administration console and the consumer storefronts from a browser:

Important

If you are having issues visiting the storefront links, you will either need to set up DNSMasq in order to map URLs to localhost or set up /etc/hosts with the heatclinic and aaahotsauces subdomains.

We recommend using Chrome since the above should be handled automatically. You’ll also want to enable insecure localhost by visiting: chrome://flags/#allow-insecure-localhost
Note

Remember to shutdown your docker services when finished in order to free up resources i.e. docker-compose down
Viewing OpenAPI Specs & Testing Endpoints

During local development or evaluation, you may find it beneficial to view API documentation around exposed services within the project. To facilitate this, we’ve provided a supporting docker image that will run in the background that includes our Open API specs for some of the core framework services along with a Swagger UI that allows users to "Try Out" various endpoints.

Next, you can visit the Open API UI by visiting:

Note

make sure you have the supporting docker container openapi-ui running

Starting Up With Other RDBMS Platforms [Alternative]

By default, the supporting services and demo application startup with support for Postgres. However, the demo is designed to also support Oracle, MySql, and MariaDB. To switch to one of the other platforms, you should do the following:

  1. Instead of the standard docker-compose startup command, use a specialized version that includes the compose file targeting your platform

    docker-compose -f docker-compose.yml -f docker-compose.mysql.yml up -d

  2. Instead of the standard spring boot run startup command, use a specialized version that includes the profile targeting your platform

    mvn spring-boot:run -Dspring.profiles.active=default,mysql

Things to Try

Once you’ve started up both the admin and the storefront. Here are a couple things you may want to try:

  • As the "Master" admin user, try switching between different applications using the site selector in the left hand navigation. Once you are working in a particular context (e.g. Heat Clinic), you can start modifying and editing items which you can then deploy to the corresponding storefront.

  • Modifying an existing product in the admin, saving those changes, and then promoting and deploying that change into production.

  • Creating a new offer that targets a specific SKU or Variant

  • Try logging in as a different admin user to view the experience for someone with limited roles and permission:

    • Username: readonly@test.com

    • Password: Pass1word!

Docker Supporting Services

What is the purpose for all of these supporting docker services?

  • the docker-compose file defines various services that aid in facilitating a full commerce experience needed for this overview project and tutorial, such as an auth service and a couple API gateways. The following is a list of all the supporting services with a brief description of their intent.

Table 1. Supporting Services Directory
Service Description

admingateway

this is a lightweight API Gateway built on top of Spring Cloud Gateway to facilitate routing for the admin console

adminweb

this is a reference image of our React Microservices Admin SPA

auth

this is a lightweight OAuth2 authorization server used to generate the necessary JWT tokens for authentication

commercegateway

this is a lightweight API Gateway built on top of Spring Cloud Gateway to facilitate routing for the storefront

commerceweb

this is a reference image of our Next.JS Commerce Storefront SPA. See Frontend Development Guide for instructions on getting this running locally.

localkafka

Official Confluent Docker Image for Kafka (Community Version)

localsolr

Broadleaf-flavored image based on Solr’s official 8.2 distro

openapi-ui

Broadleaf Open API Specs and Swagger UI

database (default Postgres)

Official Postgres 11.2 Docker Image

zk

Official Confluent Docker Image for Zookeeper

What open ports do I need for this example project?

This project will attempt to utilize the following ports:

Table 2. Reference Project Default Ports
Service Port(s)

zk

2181

adminweb

3000

open api ui

3003

commerceweb

4000

database

5432 (default postgres)

localkafka

9092, 7777 [JMX]

auth

8443, 8000 [Debug]

admingateway

8446, 8001 [Debug]

commercegateway

8456, 8014 [Debug]

localsolr

8983

FAQ

Check out the Broadleaf Microservices Knowledgebase here: https://ms-support.broadleafcommerce.com/category/69-flex-package-starter-project