This document provides the steps to configure your Broadleaf services and infrastructure to support integrated local development patterns. When we say, "integrated local development", we are referring to a frontend developer working on their local machine without having to start up any backend services. This development pattern tends to be more efficient and effective for frontend developers than requiring them to understand how to deploy the infrastructure on their local machine.
Typically, you will have a dev or staging environment that is running a slimmed down version of your production code. This is the environment you will need to change to support this pattern. The setup involves three key components: the commerce gateway, the authorization server, and the frontend app being developed locally.
Setting up the commerce gateway is pretty straightforward if you are using the Spring Cloud Gateway application we provide out-of-box.
Simply enable the cors Spring Profile when starting up the Spring Boot application.
Behind the scenes, this will engage the following properties that will enable cross-origin requests into your commerce gateway:
spring:
cloud:
gateway:
globalcors:
cors-configurations:
'[/**]':
allowCredentials: true
allowedOrigins: '*'
allowedHeaders: '*'
allowedMethods:
- 'GET'
- 'POST'
- 'PUT'
- 'PATCH'
- 'DELETE'
- 'OPTIONS'
- 'HEAD'At this point, your environment will be ready to support most local development use cases. You should be able to make HTTP requests from your local app and see that the browser does not block them. If you are not using Spring Cloud Gateway, you will need to make a similar change to which gateway or load balancer you have configured for your environment.
Setting up the authorization server has a few more steps than the gateway. Take note that this step is really only important if you want to support authentication and authorizations within the local development environments. For many, development from the perspective of an anonymous user is sufficient, and these steps won’t be necessary. For those who want to support authorization in the local development environments, here is how to do it:
|
Warning
|
It is important to understand that you are intentionally opening up a potential vulnerability in the environment these steps are taken. DO NOT take these steps in a production environment, or any environment that has sensitive information or data. |
Configure the AuthorizationServer for the application you want to develop on as "cross-origin". This can be configured within the admin, or in the auth database. This step will ensure that the SameSite policy for the session cookie is set to None, thereby allowing cross-site requests.
Add your local development URLs to the redirect URIs within the application’s AuthorizedClient. For example, you might add https://localhost:4000, https://localhost:4000/callback, and https://localhost:4000/silent-callback.html
Ensure a ForwardedHeaderFilter is registered for auth service. This is generally part of the out-of-box Spring Boot application.
Ensure that broadleaf.auth.security.useRedirectUriHost is set to false. This should generally be set to false, but if not, set it to false for this environment.
At this point, your environment should support not just cross-origin requests, but also cross-origin authentication and authorization. You should be able to register and login as a customer in these environments, as long as your frontend application supports those flows.
The only thing to note for the frontend application is that you need to be sure the HTTP requests and auth redirections are routed to the development or staging environment. If you are using Broadleaf’s OOB Next.js starter, this typically means configuring these environment variables:
NEXT_PUBLIC_AUTH_BASEURL=https://${COMMERCE_GATEWAY_HOST}/auth
NEXT_PUBLIC_CLIENT_BASE_HOST=https://${COMMERCE_GATEWAY_HOST}
NEXT_PUBLIC_GATEWAY_HOST=https://${COMMERCE_GATEWAY_HOST}
NEXT_PUBLIC_API_ORIGIN=https://${COMMERCE_GATEWAY_HOST}