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.
Download the platform-independent connector from Connector/J.
Extract the tarball into a temporary directory.
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:- Locate
context.xml
in Tomcat (typically in the directory<TomcatRoot>/conf/
). - Make a backup copy of the file
context.xml
. - Download
sample-context.xml
. - Copy the downloaded file
sample-context.xml
tocontext.xml
, overwriting the existing file.
- Locate
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’swebapps/
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.- Back up the original Solr configuration files
schema.xml
andsolrconfig.xml
. - Download the Brightspot versions of the Solr configuration file and the Solr schema file.
- Rename the downloaded configuration file to
solrconfig.xml
, and rename the downloaded schema file toschema.xml
.
- Back up the original Solr configuration files
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 directorylib/
.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
, whereport
is the port number that you specified incontext.xml
. (If the name of your .war file is notROOT.war
, then specify a context path, for examplehttp://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" />