This project contains several sub-projects that walk through various customizations and tutorial exercises that may be common in an implementation. Please refer to each sub-module’s README for more detail.
Module | Description |
---|---|
|
Intended to be the initial project structure on which the other tutorials in this project are based A basic project that shows running Broadleaf’s unified microservices admin alongside the |
|
A completed tutorial that showcases typical extensions and customizations on top of the base project |
|
A completed tutorial that showcases the creation of new domain, repositories, services, and endpoints
on top of Broadleaf’s |
💡
|
The Tutorial projects here only deploy a subset of the Broadleaf Commerce Microservices (and not the full suite of commerce services). To evaluate the full suite of commerce services, please visit https://github.com/BroadleafCommerce/MicroservicesStarter |
In order to get this reference project running locally, you will want to obtain and install the following:
Access to Broadleaf’s Docker Registry and Maven Nexus is needed in order to pull down the appropriate resources.
Once you have obtained these credentials, you will need to configure them for the dependencies below.
ℹ️
|
Contact |
You will need to have Docker Engine & Docker Compose installed locally
💡
|
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 received above.
❗
|
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. |
You’ll need to have Maven installed locally as well. Maven 3.5 or later is recommended.
Once you have maven installed, another step you need to do before you can
build the project is to configure the authentication. Maven requires it to be specified in a
file called settings.xml
that has to be in the .m2
subdirectory in a user’s home directory.
-
Create a folder called
.m2
in your home directory -
Create a file called
settings.xml
in the.m2
folder -
Copy the following contents to your
~/.m2/settings.xml
making sure to replace the credentials with the ones you received above:
<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>
Now that all of the pre-requisites are installed, let’s run the project!
Now that all of the pre-requisites are installed, let’s build and run the projects!
-
First, we’ll need to download or clone this project so that we can run everything locally on your own machine. You can utilize the
Clone or Download
button at the top right of this page. -
Once you have the project downloaded, let’s go ahead and build it using Maven. You’re going to navigate to the root folder (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:mvn clean install
ℹ️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.
-
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 the appropriate project and running:
docker-compose up -d && ./check-tutorial-services-status.sh
-
Next, you will want to start up the core backend commerce APIs by running the following command (instead of the simple
mvn spring-boot:run
command) so that you don’t have to worry about getting a valid JWT authentication token every time:mvn spring-boot:run -Pnosec
ℹ️In this project, we’ve added a maven profile called
nosec
which passes in some particular properties to disable certain api security measures. This allows us to easily demonstrate some example flows using the Admin and cURL (see Step 3) -
That’s it! Once you’ve verified that the supporting services and backend APIs are running, you can visit the administration console from a browser:
-
Admin Console: https://localhost:8446
-
Username:
[email protected]
-
Password:
Pass1word!
-
-
cURL Demo:
curl --insecure -X GET "https://localhost:8447/products?offset=0&forward=true&pageSize=50" -H "accept: application/json" -H "X-Context-Request: {\"tenantId\":\"5DF1363059675161A85F576D\",\"catalogId\":\"10\"}"
-