Running the Heat Clinic locally
Goals
This tutorial is designed to get the Heat Clinic running in your local environment using the command prompt for your operating system. By the end of this tutorial you will have the consumer-facing Heat Clinic store running locally, as well as, the Broadleaf admin, which is used to manage the Heat Clinic data.
Prerequisites
First, download the Java 8 Development Kit: either the official Oracle JDK or Open JDK
You will also need the latest version of Maven (at least version 3.3.9, version 3.5.0 is recommended)
Need help installing the pre-requisites on Windows, OSX, or Linux?
Windows Installation
Java
Download the Java 8 JDK from Oracle's website and install. After installation, in order for other dependencies to work correctly (like Maven) you need to ensure that the JAVA_HOME environment variable is set. Follow the tutorial at http://www.mkyong.com/java/how-to-set-java_home-on-windows-10/ for Windows 10 and https://kaanmutlu.wordpress.com/2013/04/26/setting-the-java_home-in-windows-7-64-bit/ for Windows 7.
These tutorials will also make the java command available on the command line (the Java installer might have already done this). To validate that everything is installed correctly, open up a command prompt (cmd.exe) and type:
» echo %JAVA_HOME%
» java -version
Those commands should print out the path to where Java is installed and then print out the Java version (which should contain 1.8 in the version)
Maven
Download the latest version of Maven from the Maven downloads section. Then, follow these additional instructions to ensure that the mvn executable is on your path.
To test that Maven was installed correctly, you should be able to type mvn -v in the command prompt and get something like:
» mvn -v
Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T08:41:47-08:00)
Maven home: C:\apache-maven-3.3.9\bin\..
Java version: 1.8.0_77, vendor: Oracle Corporation
Java home: C:\Program Files\Java\jdk1.8.0_77\jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 10", version: "10.0", arch: "amd64", family: "dos"
Mac/OSX
Java
Follow the link to install Oracle JDK 8. To verify that this is installed correctly, open up Terminal and type:
» java -version
Then, to properly set the JAVA_HOME environment variable for Maven, execute this command:
export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)
It is a good idea to put this in your
~/.bash_profileor equivalent file for your shell
Maven
The easiest way to install Maven is through a utility called Homebrew. Once Homebrew is installed open Terminal and type:
» brew install maven
To verify that it is installed correctly type mvn -v in a Terminal. You should get output like:
» mvn -v Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T10:41:47-06:00)
Maven home: /usr/local/Cellar/maven/3.3.9/libexec
Java version: 1.8.0_73, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_73.jdk/Contents/Home/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "10.11.4", arch: "x86_64", family: "mac"
Linux
Java
Use you favorite dependency management tool to download Java. Note that in Java 8 might not be the default in your distribution, and you might have to add an extra repository for the Oracle JDK. For instance, in Ubuntu, this adds the PPA for the Oracle Java 8 JDK:
» sudo add-apt-repository ppa:webupd8team/java
» sudo apt-get update
» sudo apt-get install oracle-java8-installer
You also need to set the JAVA_HOME environment variable to where the JDK is installed for Maven. The path can be determined automatically with this command:
» export JAVA_HOME=$(readlink -f /usr/bin/javac | sed "s:/bin/javac::")
You can have this environment variable set for you automatically for every shell by adding the previous line to your ~/.bashrc file.
Maven
Most likely, your package manager has a maven package. If this is the case, simply run:
» sudo apt-get install maven
Use mvn -v to verify the version; it should be at least 3.3.3.
If not, download the latest version of Maven from the Maven downloads section. Extract the directory to somewhere that you will remember, like /usr/local/apache-maven-3.3.9. Finally, add the mvn executable to your PATH environment variable with:
» export PATH=/usr/local/apache-maven-3.3.9/bin:$PATH
To verify the installation, you should be able to execute the following:
» mvn -v
Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T10:41:47-06:00)
Maven home: /usr/local/apache-maven-3.3.9
Java version: 1.8.0_77, vendor: Oracle Corporation
Java home: /usr/lib/jvm/java-8-oracle/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "4.2.0-34-generic", arch: "amd64", family: "unix"
Unzip
In order to extract the Heat Clinic files, you will need the unzip program. If it isn't installed already simply run:
» sudo apt-get install unzip
Steps
Now that all of the pre-requisites are installed, let's set up the Heat Clinic.
Install Broadleaf
Download the Community Edition.
a. Download the 5.2 Community Edition. Qualifying customers can use this edition without charge, even in production. Anyone can use it to get hands on with core Broadleaf concepts including domain, extension patterns, and more in non-production environments.
b. Once you have the correct version of the Heat Clinic downloaded, unzip it and keep note of the location.
c. At the command line for your operating system, change your directory to where the Heat Clinic is unzipped and build the project:
» mvn installThis might take a while as all of the Broadleaf dependencies and other transitive dependencies are downloaded
Start the Admin
Now let's start up the Heat Clinic admin by going into the
admindirectory from the command line and executing:» mvn spring-boot:runOnce this has finished executing, you should be able to see the Heat Clinic Admin by going to http://localhost:8081/admin in your browser. The username and password is
admin/admin.Start the Site
After this is complete, start up the Heat Clinic frontend by going into the
sitedirectory from the command line and executing:» mvn spring-boot:runOnce this has finished executing, you should be able to see the Heat Clinic by going to http://localhost:8080 in your browser
Start the API
There is an
apiproject that just contains the Broadleaf APIs. Go into theapidirectory from the command line and execute:» mvn spring-boot:runOnce this has finished, you can see the Swagger API definitions by going to http://localhost:8082/api/v1/swagger-ui.html.
The APIs start up with a default username of
broadleafapiand a randomly-generated password that shows up in your logs. You can change this by modifying the security information inApiSecurityConfigin your demo project. To use this with Swagger, hit the "Authorize" button on the top right.
Next Steps
Now that you have Broadleaf up and running, here are some places you might go to next:
- Import the Heat Clinic into your IDE
- Change the database to MySQL, Postgres, Oracle, or SQL Server
- Learn about SolrStarter
FAQ
Where is the Heat Clinic data stored? (Show Answer)
The Heat Clinic starts up with an embedded HSQL database, stored as a flatfile within the java.io.tmpdir directory. With INFO logging turned on, on startup you can see where the database file is:
2017-05-18 09:25:40.553 INFO 90729 --- [ost-startStop-1] c.b.autoconfigure.HSQLDBServer : Starting HSQL server...
2017-05-18 09:25:40.554 WARN 90729 --- [ost-startStop-1] c.b.autoconfigure.HSQLDBServer : HSQL embedded database server is for demonstration purposes only and is not intended for production usage.
[Server@447bcb66]: [Thread[localhost-startStop-1,5,main]]: checkRunning(false) entered
[Server@447bcb66]: [Thread[localhost-startStop-1,5,main]]: checkRunning(false) exited
[Server@447bcb66]: Initiating startup sequence...
[Server@447bcb66]: Server socket opened successfully in 4 ms.
[Server@447bcb66]: Database [index=0, id=0, db=file:/var/folders/5p/x301ksy93b5797hsck79gf_80000gn/T/broadleaf-hsqldb/broadleaf, alias=broadleaf] opened sucessfully in 464 ms.
[Server@447bcb66]: Startup sequence completed in 470 ms.
[Server@447bcb66]: 2017-05-18 09:25:41.042 HSQLDB server 2.3.3 is online on port 9001
[Server@447bcb66]: To close normally, connect and execute SHUTDOWN SQL
[Server@447bcb66]: From command line, use [Ctrl]+[C] to abort abruptly
You can modify this directory with the property demo.database.workingDirectory.
You can browse this database via Connect to the Local Database. You can also switch to another database such as Oracle, MySQL, Postgres or SQLServer.
Why did my data get wiped after a reboot? (Show Answer)
By default the Heat Clinic is configured to drop all tables and re-run import scripts on startup in the development runtime environment (the default for local development). In site/src/main/resources/runtime-properties/development.properties and also in admin/src/main/resources/runtime-properties/development.properties you will find these properties:
blPU.hibernate.hbm2ddl.auto=
blEventPU.hibernate.hbm2ddl.auto=
blSecurePU.hibernate.hbm2ddl.auto=
blEventPU.hibernate.hbm2ddl.auto=
There are 5 possible values for these properties:
validate- validate the database schema with the Hibernate data model, makes no changes to the database. Throws an exception if the database schema and the Hibernate model do not matchupdate- update the database schema with the Hibernate data model (e.g. add columns, foreign keys, tables). This will not change the underlying data inside the tables, but it is possible that you have invalid data after executing the update.create- on startup, this executes adropon all tables and data in the schema. Then all tables are re-created, and data load SQL is imported as specified by<unit_name>..hibernate.hbm2ddl.import_fileslike indevelopment-shared.properties.create-drop- on startup, do the same thing as thecreatevalue. On shutdown, drop the entire schema including all data and tablesnone- do not do anything when comparing the Hibernate model to the database schema
You can also control whether or not the file itself that holds the database is deleted with demo.database.clearState=true.
Where does the Heat Clinic get all of its data for initial load? (Show Answer)
All of the Broadleaf modules have sets of demo and admin security data. Each of these load scripts are within the individual Broadleaf dependency .jar files, usually in the config/bc/sql folder. If INFO logging is turned on for the class org.broadleafcommerce.common.extensibility.jpa.JPAPropertiesPersistenceUnitPostProcessor (which is the default) then you will see some output about what SQL files were inserted and their order. Example:
2017-05-18 08:22:19.766 INFO 78707 --- [ost-startStop-1] PAPropertiesPersistenceUnitPostProcessor : AutoImportStage.PRIMARY_FRAMEWORK_SECURITY
2017-05-18 08:22:19.766 INFO 78707 --- [ost-startStop-1] PAPropertiesPersistenceUnitPostProcessor : [order:1000] config/bc/sql/load_admin_permissions.sql,config/bc/sql/load_admin_roles.sql,config/bc/sql/load_admin_menu.sql
2017-05-18 08:22:19.766 INFO 78707 --- [ost-startStop-1] PAPropertiesPersistenceUnitPostProcessor : AutoImportStage.PRIMARY_PRE_MODULE_SECURITY
2017-05-18 08:22:19.766 INFO 78707 --- [ost-startStop-1] PAPropertiesPersistenceUnitPostProcessor : AutoImportStage.PRIMARY_MODULE_SECURITY
2017-05-18 08:22:19.766 INFO 78707 --- [ost-startStop-1] PAPropertiesPersistenceUnitPostProcessor : [order:3000] config/bc/sql/load_menu_admin_security.sql
How can I add more files to the Heat Clinic data load?
At this point, it is likely that you should start to version your database and move to Liquibase to manage your database updates. You can then write changelogs to apply updates that will automatically run across your team and whenever you move to new environments.
Alternatively, if you are not ready to go to Liquibase and would rather just tie some new SQL to the Broadleaf SQL import process, you can add a new @Configuration class with an AutoImportSQL bean within the core project like so:
@Configuration
@Conditional(ImportCondition.class)
public class MyDataLoad {
@Bean
public AutoImportSql blPrivateDemoTenantData() {
return new AutoImportSql(AutoImportPersistenceUnit.BL_PU,"/sql/mycustomfile.sql", AutoImportStage.PRIMARY_LATE);
}
}
Why do I see error messages like 'HHH000389: Unsuccessful: alter table ...'? (Show Answer)
When the Heat Clinic first starts up, you might see a lot of these types of error messages in your logs:
[ERROR] 08:38:08 SchemaExport [admin][][] - HHH000389: Unsuccessful: alter table BLC_PAYMENT_LOG drop constraint FKA43703453E2FC4F9
[ERROR] 08:38:08 SchemaExport [admin][][] - user lacks privilege or object not found: PUBLIC.BLC_PAYMENT_LOG
[ERROR] 08:38:08 SchemaExport [admin][][] - HHH000389: Unsuccessful: alter table BLC_PAYMENT_LOG drop constraint FKA43703457470F437
[ERROR] 08:38:08 SchemaExport [admin][][] - user lacks privilege or object not found: PUBLIC.BLC_PAYMENT_LOG
[ERROR] 08:38:08 SchemaExport [admin][][] - HHH000389: Unsuccessful: alter table BLC_PGTMPLT_FLDGRP_XREF drop constraint FK99D625F66A79BDB5
[ERROR] 08:38:08 SchemaExport [admin][][] - user lacks privilege or object not found: PUBLIC.BLC_PGTMPLT_FLDGRP_XREF
This is a known bug that exists in Hibernate. This only occurs when the schema has never been created before and the hbm2ddl.auto is set to create or create-drop. These messages are harmless and can safely be ignored.