Advanced Installation¶

The advanced installation gives you maximal access to develop and customize all of Brightspot’s capabilities. This scenario requires that you manually install and configure the system requirements, use Maven to build and package the Brightspot platform into a WAR, and deploy it in the Tomcat application server. Plan on 30 to 45 minutes to complete this installation.

System Requirements¶

To perform an advanced installation of Brightspot, you’ll need the following:

Java SE Development Kit version 8u172 (1.8.0_172) or later

Maven 3+

MySQL 5.6.*

Solr 4.8.1

Tomcat 8

Installation Procedure¶

Download and install the software listed in System Requirements.
Create an empty database in MySQL.
Configure Tomcat to run the Brightspot platform.
Install Solr into Tomcat.
Build a Brightspot project with Maven.
Start the application server.

MySQL¶

Run MySQL locally, and create an empty database to be used by the Brightspot platform. You can perform MySQL operations from an optional GUI tool such as MySQLWorkbench. Alternatively, you can use the MySQL command-line tool.

You can give the database any name. The following command creates a database called “brightspot”:

CREATE DATABASE brightspot CHARACTER SET utf8 COLLATE utf8_general_ci;

Record the database name; you will specify it in the Tomcat context.xml file.

Tomcat¶

Configure Tomcat to run Brightspot projects:

Add MySQL connector.

Download the MySQL Connector JAR file for Tomcat and place it in the Tomcat lib folder. For example:
```
cp mysql-connector-java-5.*.jar <TomcatRoot>/lib
```
Add a local storage directory.

Brightspot can store uploaded files locally in a media directory. Create this directory in the Tomcat webapps directory. For example:
```
mkdir -p <TomcatRoot>/webapps/media
```
Replace the default context.xml file in Tomcat with a new file containing the default Brightspot configurations:
1. Locate context.xml in Tomcat (typically in the <TomcatRoot>/conf folder).
2. Make a backup copy of the file context.xml.
3. Download sample-context.xml.
4. Copy the downloaded file sample-context.xml to context.xml, overwriting the existing file.
In context.xml, replace the following placeholders:

DATABASE_NAME with the name of the empty MySQL database that you previously created.

DATABASE_USER with the name of the user that created the MySQL database.

DATABASE_PASS with the password that created the MySQL database.

TOMCAT_PATH with the path to Tomcat.

Note

The context.xml file referenced in this topic is a basic version of the Brightspot configuration. However, you can expand context.xml for future projects, or use multiple context.xml files for multiple Brightspot projects. The recommended best practice is to run an instance of Tomcat for each Brightspot project. The context.xml file will contain project-specific settings and point to a project specific database. When running multiple projects locally, you can stop Tomcat or use a different port for each project to run them concurrently.

Solr¶

Solr is used as a text matching database in the Brightspot platform. It contains the same data that is stored in the SQL database.

Install Solr into Tomcat:

Place the solr.war file in the Tomcat webapps directory, for example:
```
cp <SolrRoot>/example/webapps/solr.war <TomcatRoot>/webapps
```
Copy the Solr database directory into the Tomcat root directory, for example:
```
cp -r <SolrRoot>/example/solr <TomcatRoot>
```
In the <TomcatRoot>/solr/collection1/conf folder, replace two Solr configuration files with Brightspot specific configurations.
1. Back up the original Solr configuration files, “schema.xml” and “solrconfig.xml”.
2. Download the Brightspot versions of the Solr config file and the Solr schema file.
3. Rename the config file to “solrconfig.xml”. Rename the schema file to “schema.xml”.
Edit the solr.xml file in the <TomcatRoot>/solr folder:

Replace the default host post with the Tomcat port <int name="hostPort">${jetty.port:8080}</int>.
Copy all of the files in the <SolrRoot>/example/lib/ext folder into the Tomcat lib directory, for example:
```
cp <SolrRoot>/example/lib/ext/* <TomcatRoot>/lib
```

Build a Brightspot Project¶

You build a Brightspot project from a Maven archetype. The target of the Maven build is the Brightspot platform packaged in a WAR file and the Styleguide developer platform.

Get the starter Brightspot project.

You can use either Git or Maven to get the project. Use Maven if no Git repository exists.

To use Git:
1. Clone the brightspot-cms repository on your local drive.
2. Navigate to the top-level folder of the repository where the pom.xml file resides. This file defines Brightspot and Dari dependencies.
To use Maven:
1. Run the following archetype on the command line:
```
mvn archetype:generate -B \
-DarchetypeRepository=http://artifactory.psdops.com/public/ \
-DarchetypeGroupId=com.psddev \
-DarchetypeArtifactId=cms-app-archetype \
-DarchetypeVersion=<snapshotVer> \
-DgroupId=<groupId> \
-DartifactId=<artifactId>
```
  Replace:
  
  snapshotVer with the Brightspot build version, for example, 3.2-SNAPSHOT.
  
  groupId with a value that will serve as a Java package name for any Brightspot classes that you might add. Maven will create a source directory structure based on the package name. For example, if you specify com.myApp, the Brightspot project will include this directory for adding Brightspot classes: src/main/java/com/myApp.
  
  artifactId with a project name like tutorial. This will be used for the top-level folder of the Brightspot project.
  
  Note
  
  Windows users must run the archetype on one line without breaks (\), for example:
  
  mvn archetype:generate -B -DarchetypeRepository=http://artifactory.psdops.com/public/ -DarchetypeGroupId=com.psddev -DarchetypeArtifactId=cms-app-archetype -DarchetypeVersion=<snapshotVer> -DgroupId=<groupId> -DartifactId=<artifactId>
  
  Note
  
  If you use maven-archetype-plugin version 3.0.0 or higher, you might get the following warning (and possibly a build failure):
  
  [WARNING] Archetype not found in any catalog. Falling back to central repository.
  
  To avoid this warning, explicitly specify the 2.4 plugin version in the command.
  
  Replace mvn archetype:generate
  
  with mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate
2. Navigate to the top-level folder of the Maven project where the pom.xml file resides. This file defines Brightspot and Dari dependencies.
Build the Brightspot project with Maven:
```
mvn clean package
```
This generates a target directory with the Brightspot platform packaged in a WAR file.
Copy the generated WAR file from the target directory to the Tomcat webapps directory and rename it as desired. For example:
```
cd tutorial/target
cp tutorial-1.0-SNAPSHOT.war <TomcatRoot>/webapps/ROOT.war
```

Start the Application Server¶

Navigate to the Tomcat root folder and start the application server:
```
./bin/startup.sh or ./bin/startup.bat
```
Tomcat deploys the Brightspot platform.
In a web browser, access Brightspot at http://localhost:<port>/cms, where port is the port number that you specified in context.xml.

Note

If the name of your WAR file is not ROOT.war, then specify a context path, for example http://localhost:8080/my-bsp-application/cms.

The Brightspot login page appears. This is the default landing page.

Follow up the Brightspot deployment with the following actions:
- If Java heap size errors appear in the Tomcat logs, change the memory allocation in the Tomcat catalina.sh file, found at <TomcatRoot>/bin/catalina.sh. Add the following line directly above the # OS specific support section:
```
# ----- Adding more Memory
CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=256M -Djava.awt.headless=true"
```
- Insufficent free space warnings like the following might appear in the Tomcat logs:
```
org.apache.catalina.webresources.Cache.getResource
Unable to add the resource at [/WEB-INF/lib/aws-java-sdk-workspaces.jar] to the cache because there was insufficient free space available after evicting expired cache entries -
consider increasing the maximum size of the cache
```
  To prevent these warnings, add the following setting to <TomcatRoot>/conf/context.xml.
```

<Resources cachingAllowed="true" cacheMaxSize="100000" />
```
- Check for new Brightspot versions. See Release Notes.