Skip to content

spotfire-server container

About this image

This directory contains the official container recipe for Spotfire® Server.

What is the Spotfire Server?

Spotfire® Server is the administrative center of the Spotfire environment.

The Spotfire Server:

  • Facilitates configuration and administration of the Spotfire environment.
  • Provides user authentication and role-based authorization.
  • Provides centralized storage of Spotfire analysis files and metadata. The library items reside in the Spotfire database.
  • Provides a centralized point of data access and metadata management for relational data sources.
  • Provides access point for all client connections.
  • Routes clients to the appropriate service instance, based on smart default routing or configured routing rules.
  • Distributes software updates to services and clients.

For a quick overview, see the Introduction to the Spotfire environment ⧉.

For more information on the Spotfire product family, see the Spotfire® Documentation ⧉.

How to build this image

The easiest and recommended way to build all the Spotfire container images is using the provided containers/Makefile. See Spotfire Cloud Deployment Kit on GitHub ⧉.

You can also build this image individually. Follow the instructions below or adjust them according to your needs.

Prerequisites:

Steps:

  1. Copy the spotfireserver-<version>.x86_64.tar.gz package into the build/ directory within this directory.
  2. From the <this-repo>/containers folder, run make spotfire-server to build this image, or make spotfire-server --dry-run to just view the commands.

How to use this image

Requirements:

  • To bootstrap (initial setup) the spotfire-server container you need connectivity access to a working database server configured with the Spotfire database schemas and valid credentials.

Note: The Spotfire database must have configured valid schemas corresponding to the same Spotfire release.

Note: The Spotfire database schemas can be created with the spotfire-config container.

Start a Spotfire Server container

You can start an instance of the Spotfire Server container with: 

docker run -d --rm -p8080:8080 \
  -e ACCEPT_EUA=Y \
  -e SPOTFIREDB_CLASS="${SPOTFIREDB_CLASS}" \
  -e SPOTFIREDB_URL="jdbc:${SPOTFIREDB_DRIVER}://${SPOTFIREDB_HOST}:${SPOTFIREDB_PORT}/${SPOTFIREDB_DBNAME}" \
  -e SPOTFIREDB_USERNAME="${SPOTFIREDB_USERNAME}" \
  -e SPOTFIREDB_PASSWORD="${SPOTFIREDB_PASSWORD}" \
  -e TOOL_PASSWORD="${SPOTFIRE_CONFIG_TOOL_PASSWORD}" \
  spotfire/spotfire-server

Note: This Spotfire container image requires setting the environment variable ACCEPT_EUA. By passing the value Y to the environment variable ACCEPT_EUA, you agree that your use of the Spotfire software running in this container will be governed by the terms of the Cloud Software Group, Inc. End User Agreement ⧉.

For example, starting a Spotfire Server container instance connecting to a Spotfire database with PostgreSQL as the underlying database server:

docker run -d --rm -p8080:8080 \
  -e ACCEPT_EUA=Y \
  -e SPOTFIREDB_CLASS=org.postgresql.Driver \
  -e SPOTFIREDB_URL=jdbc:postgresql://$SPOTFIREDB_HOST/spotfiredb \
  -e SPOTFIREDB_USERNAME=spotfire \
  -e SPOTFIREDB_PASSWORD=spotfirepassword \
  -e TOOL_PASSWORD=toolpassword \
  spotfire/spotfire-server

Note: For details on variables for connecting to other supported databases, see Database drivers and database connection .

Environment variables

Database connection

It is required to provide the Spotfire database connection details.

Note: All SPOTFIREDB_* environment variables are required unless an existing bootstrap.xml exists in /opt/spotfire/spotfireserver/tomcat/webapps/spotfire/WEB-INF during startup.

Note: Make sure to keep a backup before upgrading the database.

For more information, see the database drivers and database connection URLs ⧉ and bootstrap command ⧉ documentation pages.

Tomcat and JVM settings

  • CATALINA_INITIAL_HEAPSIZE - The initial JVM heap size for the Spotfire Server. Default: 512M.
  • CATALINA_MAXIMUM_HEAPSIZE - The maximum JVM heap size for the Spotfire Server. Default: 1G.
  • CATALINA_OPTS - Tomcat runtime options used for the Spotfire Server. Default: -Djava.net.preferIPv4Stack=true.

Logging

The following variables define the default logging:

Other variables

The following predefined startup checks are available:

  • STARTUPCHECK_TIMEOUT_SECONDS - Timeout in seconds for the startup check. Default: 60 seconds.
  • STARTUPCHECK_ADMIN_USER - Verify if administration user is set. Values: Y/N. Default: N.
  • STARTUPCHECK_VALID_DEPLOYMENT - Verify if a valid package deployment is in place. Values: Y/N. Default: N.

The following variables define spotfire server site behavior:

  • SITE_NAME - Define which site the server should belong to. Default: Default.
  • ENCRYPTION_PASSWORD - The password for encrypting passwords that are stored in the database. See --encryption-password for the bootstrap ⧉ command. Default: If you do not set this option, a static password is used.

See documentation related to sites ⧉ for more information.

Advanced configuration

Using custom logging

The spotfire-server container uses log4j2 ⧉ for logging configuration. The logging configuration is stored in the log4j2.xml file. The default configuration uses the log4j Socket Appender ⧉.

You can modify the default configuration using any of the existing log4j2 Appenders ⧉ to forward the logs to your preferred logging collector.

For doing that, you can for example mount your custom log4j2.xml: 

docker run ... -v /local/path/to/custom-log4j2.xml:/opt/spotfire/spotfireserver/tomcat/spotfire-config/log4j2.xml

Note: When overriding the default log4j2.xml, it's recommended to keep the overall file structure to minimize the number of changes.

Using a shared folder for library export

By default, the Spotfire library content can be imported from and exported to the path: /opt/spotfire/spotfireserver/tomcat/application-data/library. You can mount this directory to an external volume that is shared between all Spotfire servers in the cluster.

Example: 

docker run ... -v /local/path/to/library:/opt/spotfire/spotfireserver/tomcat/application-data/library

Once an export and import location is set to an external volume, exported and imported library content can be transferred from and to this volume.

For more information on importing and exporting, see:

Using custom jar files

You can extend the Spotfire server by adding additional jar files, such as JDBC drivers.

For example, to add JDBC drivers to the Spotfire Server, place them in the /opt/spotfire/spotfireserver/tomcat/custom-ext directory. You can achieve this by mounting a volume containing the drivers to this path:

docker run ... -v /local/path/to/custom-ext:/opt/spotfire/spotfireserver/tomcat/custom-ext/

Similarly, to add JDBC drivers for Spotfire Information Services, place them in the /opt/spotfire/spotfireserver/tomcat/custom-ext-informationservices directory. You can mount a volume with the drivers to this path as well:

docker run ... -v /local/path/to/custom-ext-informationservices:/opt/spotfire/spotfireserver/tomcat/custom-ext-informationservices/

For more information about using extra jar files, and the custom-ext and custom-ext-informationservices folders, see:

Alternatively you can extend this image.

How to extend this image

This example shows how to create a new container image, based from the spotfire-server image, to include custom drivers:

  1. First follow the instructions for how to build this image.
  2. Create a new Dockerfile in a new directory (e.g., spotfire-server-extended): 
    FROM spotfire/spotfire-server
COPY custom-ext/ /opt/spotfire/spotfireserver/tomcat/custom-ext
  3. Include your custom drivers in the custom-ext directory within that build directory.
  4. Build the new custom image: 
    docker build -t spotfire-server-extended .

You can now use the container image spotfire-server-extended.

Using the Spotfire Server configuration tool

Note: You can run the Spotfire config-tool from the spotfire-server container for troubleshooting purposes. Anyhow, we recommend using the dedicated spotfire-config container for using the Spotfire config-tool.

The spotfire server configuration tool is available in a running Spotfire server container as the command config.sh. The --tool-password needed to run many commands is stored in the TOOL_PASSWORD environment variable.

Example: Get a shell into a spotfire server container and use the configuration tool

# Start a shell in the container
host $ docker exec -it spotfire-server-container bash

# Export the configuration
spotfire-server-container $ config.sh export-config --tool-password="${TOOL_PASSWORD}"

For more information, see the Command-line reference ⧉.