Advanced Installation¶

The advanced installation lets you customize Brightspot to your organization’s requirements. 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 the .war to the Tomcat 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:

Installation Procedure¶

Download and install the software listed in System Requirements.
Create an empty database as described in Creating a Project Database.
Configure Tomcat to run Brightspot as described in Configuring Tomcat to Run Brightspot.
Install Solr into Tomcat as described in Installing Solr into Tomcat.
Build Brightspot as described in Building a Brightspot Project.
Start the application server as described in Starting the Application Server.

Creating a Project Database¶

Run MySQL locally, and create an empty project database. 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.

Configuring Tomcat to Run Brightspot¶

To configure Tomcat to run Brightspot projects:

Install Tomcat’s MySQL connector.
1. Download the platform-independent connector from Connector/J.
2. Extract the tarball into a temporary directory.
3. Copy the .jar file to Tomcat’s lib/ directory.
```
cp <directory>/mysql-connector-java-VERSION.jar <TomcatRoot>/lib
```
Add a local storage directory media/.
```
mkdir -p <TomcatRoot>/webapps/media
```
Replace the default context.xml file in Tomcat with a new file containing the default Brightspot configuration:
1. Locate context.xml in Tomcat (typically in the directory <TomcatRoot>/conf/).
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 created in the section Creating a Project Database.
- 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.

The file context.xml referenced in this topic provides a basic Brightspot configuration. You can modify context.xml to enable or disable features, or use multiple context.xml files for multiple Brightspot projects. As a best practice, run each Brightspot project on a separate Tomcat instance, and the associated file context.xml contains the project-specific settings and points 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.

Installing Solr into Tomcat¶

Brightspot uses Solr as a text-matching database. Solr contains the same data that is stored in the SQL database.

To integrate Solr with Tomcat:

Place the file solr.war into Tomcat’s webapps/ directory.

cp <SolrRoot>/example/webapps/solr.war <TomcatRoot>/webapps/

Copy the Solr database directory into the Tomcat root directory.
```
cp -r <SolrRoot>/example/solr <TomcatRoot>/
```
In the directory <TomcatRoot>/solr/collection1/conf/, replace the two Solr configuration files with the Brightspot-specific configurations.
1. Back up the original Solr configuration files schema.xml and solrconfig.xml.
2. Download the Brightspot versions of the Solr configuration file and the Solr schema file.
3. Rename the downloaded configuration file to solrconfig.xml, and rename the downloaded schema file to schema.xml.
Open the file <TomcatRoot>/solr/solr.xml, and replace the default host port with the Tomcat port:
```
<int name="hostPort">${jetty.port:8080}</int>
```
Copy all of the files in the directory <SolrRoot>/example/lib/ext/ into the Tomcat directory lib/.
```
cp <SolrRoot>/example/lib/ext/* <TomcatRoot>/lib/
```

Building 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.

To build Brightspot:

Ensure your file ~/.m2/settings.xml contains the following entries:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <pluginGroups>
        <pluginGroup>com.psddev</pluginGroup>
    </pluginGroups>

    <profiles>
        <profile>
            <id>brightspot-express</id>
            <repositories>
                <repository>
                    <id>archetype</id>
                    <url>https://artifactory.psdops.com/public</url>
                    <snapshots>
                        <updatePolicy>always</updatePolicy>
                    </snapshots>
                </repository>
            </repositories>
        </profile>
    </profiles>

    <activeProfiles>
        <activeProfile>brightspot-express</activeProfile>
    </activeProfiles>
</settings>

Generate a new Brightspot project by running the following on the command line:
```
bash <(curl -s https://s3.amazonaws.com/psddev/starterkit.sh) PROJECT_NAME BRIGHTSPOT_VERSION
```
where
- PROJECT_NAME is your project name (name is used for artifact, so no dashes).
- BRIGHTSPOT_VERSION is the version of Brightspot you are using.
This command runs the Archetype, Materialize Express Core, copies in Brightspot-Styleguide, and creates a default theme brightspot-theme-dk in your project.
Change to the directory PROJECT_NAME, and view the README for development guidance.

You can access your project’s .war file in the directory site/build/libs/.

Starting the Application Server¶

To start the Brightspot application server:

Change to the Tomcat root folder.
Start the application server using one of the following commands:
```
./bin/startup.sh
./bin/startup.bat
```
Point a web browser to http://localhost:<port>/cms, where port is the port number that you specified in context.xml. (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.

Troubleshooting¶

Heap Size Errors¶

If Java heap size errors appear in the Tomcat logs, change the memory allocation in the Tomcat file <TomcatRoot>/bin/catalina.sh. Add the following line directly above the section # OS specific support:

# ----- Adding more Memory
CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=256M -Djava.awt.headless=true"

Insufficient Free Space¶

Insufficient free space warnings such as 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:

<!-- Set caching allowed -->
<Resources cachingAllowed="true" cacheMaxSize="100000" />