brightspot/tomcat repository overview

⁠Brightspot Local Development Docker Containers

These containers are intended for local development only, and are optimized for this use case. For production use, please contact Brightspot⁠.

The latest releases and their recommended Docker Compose configuration will always be documented in this README.

⁠Docker Compose Instructions

1. Download and install Docker Desktop and ensure it is running: https://www.docker.com/products/docker-desktop⁠
2. Create a file in the root of your project called docker-compose.yml with the following contents (replace "${my-project}" with your project name or the appropriate values):

services:
  mysql:
    image: brightspot/mysql:percona80-19
    ports:
      - 3306:3306
    volumes:
      - mysql-data:/var/lib/mysql
      - mysql-logs:/var/log/mysql
  opensearch:
    image: brightspot/opensearch:3.3.2-schema3-28
    environment:
      - discovery.type=single-node
    ports:
      - 9200:9200
    volumes:
      - opensearch-data:/usr/share/opensearch/data
  opensearch-dashboards:
    image: brightspot/opensearch-dashboards:3.3.0-27
    depends_on:
      opensearch:
        condition: service_healthy
    ports:
      - 5601:5601
    environment:
      - OPENSEARCH_HOSTS=["http://opensearch:9200"]
  tomcat:
    image: brightspot/tomcat:10.1.57-jdk11-97
    hostname: "${my-project}.brightspot"
    depends_on:
      mysql:
        condition: service_healthy
      opensearch:
        condition: service_healthy
    ports:
      - 5005:5005
      - 9010:9010
    volumes:
      - .:/code:cached
      - $HOME/.aws/credentials:/etc/aws/credentials:cached
      - storage-data:/servers/tomcat/storage
    environment:
      - ROOT_WAR=/code/web/build/libs/${my-project}-web-1.0.0-SNAPSHOT.war
      - CONTEXT_PROPERTIES=/code/docker-context.properties
      - CONTEXT_PROPERTIES_OVERRIDES=/code/docker-context-overrides.properties
      - LOGGING_PROPERTIES=/code/docker-logging.properties
      - AWS_PROFILE=psd-${my-project}
      - ENABLE_JACOCO=false
      - ENABLE_JFR=false
  apache:
    image: brightspot/apache:2.4-dims3.3.31-69
    depends_on:
      tomcat:
        condition: service_healthy
    ports:
      - 80:80
      - 443:443
    volumes:
      - storage-data:/var/www/localhost/htdocs/storage
volumes:
  mysql-data:
  mysql-logs:
  opensearch-data:
  storage-data:

• Ensure the relative path to the war file is correct!
• If you plan on restoring MySQL backups using the restore script, make sure the version of MySQL matches the version running in your production environments.

1. Create a file in the root of your project called docker-context.properties with the following contents:

Note: These context properties are specific to brightspot/opensearch:3.3.2-schema3-28. Replace them with the appropriate properties for your search database if your project still uses Solr (brightspot/solr images remain available).

dari/database/brightspot/delegate/opensearch/class=com.brightspot.opensearch.OpenSearchDatabase
dari/database/brightspot/delegate/opensearch/client/class=com.brightspot.opensearch.common.HttpOpenSearchClientSupplier
dari/database/brightspot/delegate/opensearch/client/baseServerUrl=http://opensearch:9200
dari/database/brightspot/delegate/opensearch/groups=-* +cms.content.searchable
dari/database/brightspot/delegate/opensearch/index=brightspot-search
dari/database/brightspot/delegate/opensearch/saveData=false

1. Start the containers using docker-compose up or docker-compose up -d. See the docker-compose documentation⁠ for other options.

• NOTE: Only one container per published port can run at the same time. If you want to run two docker containers at the same time, make sure you publish different port numbers (See the Docker documentation⁠ for more details).

1. Access Brightspot at http://localhost/cms⁠

⁠Environment Variables

⁠ROOT_WAR

ROOT_WAR contains the path in the container to the project war file.

The war is expanded into webapps/ROOT when the container starts and again on each reloader-triggered restart, whenever the war is newer than the expanded copy. After rebuilding the war, run docker-compose restart tomcat to deploy it.

⁠REMOVE_HIKARI

Whether to remove WEB-INF/lib/HikariCP*.jar from the expanded war so the HikariCP provided in tomcat/lib is used, matching the production containers. Set to false to keep the war's own copy.

Defaults to true.

REMOVE_HIKARI=false

⁠CONTEXT_PROPERTIES

CONTEXT_PROPERTIES contains the path to a properties file that will be parsed and added as <Environment> elements in tomcat's context.xml.

For example, docker-context.properties:

dari/debugUsername=debug
dari/debugPassword=12345
dari/debugRealm=Brightspot-Docker

is transformed into context.xml:

<Environment name="dari/debugUsername" value="debug" type="java.lang.String"/>
<Environment name="dari/debugPassword" value="12345" type="java.lang.String"/>
<Environment name="dari/debugRealm" value="Brightspot-Docker" type="java.lang.String"/>

⁠CONTEXT_PROPERTIES_OVERRIDES

CONTEXT_PROPERTIES_OVERRIDES contains the path to a properties file that will be parsed and added after the CONTEXT_PROPERTIES (see above). This allows you to maintain a shared, project-wide configuration and to add local (i.e., not version controlled) values.

Note: If you duplicate values between CONTEXT_PROPERTIES and CONTEXT_PROPERTIES_OVERRIDES, the original value from CONTEXT_PROPERTIES will be replaced with the value in CONTEXT_PROPERTIES_OVERRIDES. If you need to replace the entire configuration, you can alternatively set a different path for CONTEXT_PROPERTIES in your docker-compose.override.yml with the modified version instead.

⁠LOGGING_PROPERTIES

LOGGING_PROPERTIES contains the path to a properties file that will be appended to tomcat's logging.properties.

For example, docker-logging.properties:

com.my.package.level = FINE
com.my.package.MyClass.level = FINE
com.other.package.NoisyClass.level = SEVERE

⁠INIT_SH

INIT_SH contains the path to an initialization script that will be executed when the container starts.

Example:

environment:
  - INIT_SH=/code/docker-tomcat-init.sh

NOTE: Make sure docker-tomcat-init.sh is executable!

⁠AWS_PROFILE

Access to AWS services via your host credentials file is a two-step process:

1. Ensure that your ~/.aws/credentials file is mounted as /etc/aws/credentials in the docker container (See: docker-compose.yml above)

2. Add lines like

- AWS_PROFILE=psd-${my-project}
- AWS_REGION=us-east-1

to your docker-compose.yml under environment: and run docker-compose up to apply the change. Note that us-east-1 is already provided as the default region, so you should only have to override this if you need to test with a different region.

Now any changes to your host credentials file (via beam credentials, for example) will be accessible to the DefaultAWSCredentialsProviderChain in the docker container.

⁠ENABLE_JFR

Enables Java Flight Recorder on the Tomcat process.

If Tomcat is started with ENABLE_JFR=true, a JFR dump can be generated using the command:

docker-compose exec tomcat jfr-dump.sh

By default, this will create a file in /code. Use the JFR_DIR environment variable to override this default if desired, or invoke jfr-dump.sh with a filename as the first argument.

The JFR dump file can be analyzed using JDK Mission Control⁠.

⁠HEAP_PERCENT

Percentage of the host's total memory to allocate to the Tomcat JVM heap (-Xms/-Xmx). Must be an integer between 1 and 100. Invalid values fall back to the default.

Defaults to 40.

HEAP_PERCENT=25

⁠ENABLE_JACOCO

Enable JaCoCo for code coverage analysis. Note this will disable the Reloader.

ENABLE_JACOCO=true

⁠JACOCO_OPTS

Options to pass to Jacoco. These will automatically be included in CATALINA_OPTS.

Defaults to append=false.

JACOCO_ARGS=destfile=/code/web/build/jacoco/playwright.exec,append=false,classdumpdir=/code/web/build/jacoco-classes/

⁠TEMPLATE_CONFIG

If TEMPLATE_CONFIG contains the path to a YAML file (for instance TEMPLATE_CONFIG=/code/docker-template.yml), the file will be used to populate the ERB templates listed in /etc/docker/templates.

For example:

data:
  brightspot:
      extra_dari_db: otherdatabase
      extra_resources:
        - name: database1 # Required
          minimum_idle: 4 # Default: 2
          idle_timeout: 20000 # Default: 10000
          maximum_pool_size: 16 # Default: 12
          max_lifetime: 60000 # Default: 30000
          connection_timeout: 2000 # Default: 1000
          host: host # Default: localhost
          port: 3306 # Default: 3306
          database_name: database1 # Default: 'name' property value
          user: user # Required
          password: password # Required
        - name: database2
          minimum_idle: 4
          idle_timeout: 20000
          maximum_pool_size: 16
          max_lifetime: 60000
          connection_timeout: 2000
          host: host
          port: 3306
          database_name: database2
          user: user
          password: password

This populates the @data['brightspot']['extra_dari_db'] setting found in /servers/tomcat/conf/context.xml.erb and /servers/tomcat/conf/server.xml.erb.

It will also create additional, extra resource links in /servers/tomcat/conf/server.xml.erb

Future template configs will be documented here as they are developed.

⁠SSL

SSL is enabled on the Apache server. In order to trust the certificate so any domain will work, run the following commands on your Mac:

curl -O https://psddev.s3.amazonaws.com/brightspot-docker-ca.pem
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain brightspot-docker-ca.pem

⁠Caching

HTTP Request caching is provided via Apache mod_cache⁠ only if Cache-Control headers are found on the response.

To disable mod_cache altogether, add an environment variable to the apache container: DISABLE_CACHE=true

⁠Image Placeholder

When mod_dims cannot fetch a source image, or a /dims4/ request has a bad signature or arguments, it responds with a placeholder image baked into the apache container (dims-no-image.png, the same one the production containers serve) and the matching error status. To use a different placeholder, set DIMS_NO_IMAGE_URL on the apache container to an http:// or file:/// URL.

⁠Task Host

The only purpose of the hostname property is to provide a consistent hostname that can be published in site settings as a task host.

⁠Debugger

Remote debugging is exposed on port 5005.

⁠JMX

JMX provides a standard way to monitor Brightspot's performance, resource consumption, and manage various runtime aspects. This is enabled by default.

Connect to localhost:9010 using a tool such as JConsole⁠ or VisualVM⁠.

This port can be customized with the environment variable JMX_PORT. Just make sure you use the same value on both sides in the ports configuration - it must be the same port inside and outside the Docker network.

⁠Local Development (Reloader)

Note: if you are using version 4.1.8 or newer of the Brightspot Gradle Plugin and have added 'systemProp.codePath=/code' to your gradle.properties, this step is unnecessary.

Create a second file docker-compose.override.yml in the root of your project with the following contents:

services:
  tomcat:
    volumes:
      - $PWD:$PWD:cached

This will allow Brightspot to scan the host filesystem to automatically recompile Java source files.

⁠Useful commands and tips

Add this function to your ~/.bash_profile:

function d() {
  docker-compose exec $1 bash --login;
}

Use this to log in to each container by name from the project directory, for example:

$ d tomcat
[brightspot tomcat:~]$ cat /servers/tomcat/conf/context.xml

These commands can be executed on the command line if your current working directory is inside the project.

• Restart a single container
  • docker-compose restart tomcat
• Stop the project docker container (This does not delete data)
  • docker-compose stop
• Start a stopped docker container
  • docker-compose start or docker-compose start -d to detach and run it in the background
• Delete container
  • docker-compose down
  • Note: This does not delete data stored in named volumes.
• Delete unused volumes
  • docker volume prune
• Start with Docker Sync
  • docker-sync-stack start
• Tail the tomcat logs
  • docker-compose logs -f tomcat
• Increase the memory available to Docker to 4 GB
  • https://forums.docker.com/t/how-to-increase-memory-size-that-is-available-for-a-docker-container/78483⁠
• Run an interactive shell in the project Docker container
  • docker-compose exec tomcat bash
• Restore database backups
  • First shut down all containers:
    • docker-compose stop or Ctrl+C if running in the foreground
    • NOTE: This will only work if the mysql service has been started successfully at least once.
  • Then run the restore script on the mysql service:
    • docker-compose run mysql restore mysql -e qa --user ${UserName} --project ${DatabaseName} --account ${Account} --renamedb ${Project} --region=${Region}
      • Container - container name typically project name
      • UserName - Ldap Username
      • Project - Project Name
      • DatabaseName - Typically project name
      • Account - AWS account
      • Region - (Optional) AWS Region
    • Example docker-compose run mysql restore mysql -e qa --user bob --project myproject --account psd-myproject --renamedb myproject --region=us-west-1
  • Then restart all containers:
    • docker-compose start

⁠Upgrading MySQL images

For projects running mysql5.6 or percona5.6, follow these steps to upgrade to percona57 and then optionally to percona80. Every user will need to do follow these steps individually, as every user has their own independent MySQL data.

If you don't care about your existing data, you can skip these steps and just delete your mysql volume, then update the mysql image to percona57 or percona80 as desired.

1. If existing data is important, make a backup of your current MySQL volume⁠.

2. Shut down Docker

   $ docker compose down
   

   Copy

3. Update the mysql image in docker-compose.yml to percona57-3

   mysql:
     image: brightspot/mysql:percona57-3
   

   Copy

4. Run the following:

   $ docker compose up -d mysql
   $ docker compose exec mysql mysql_upgrade
   $ docker compose down mysql
   

   Copy

5. Start Docker as normal and ensure the CMS and frontend load. At this point you have successfully upgraded to Percona 5.7 and can stop.

6. If you want to continue and upgrade to percona80, run the following:

   $ docker compose exec mysql mysql --user=root --password
   mysql> SET GLOBAL innodb_fast_shutdown = 0;
   mysql> exit
   

   Copy

   then shut down Docker:

   $ docker compose down
   

   Copy

7. Update the mysql image in docker-compose.yml to percona80-11

   mysql:
     image: brightspot/mysql:percona80-11
   

   Copy

8. Run the following (the mysql uid changed so existing files need to be updated to the new uid):

   $ docker compose run --rm mysql sh
   $ sudo find /var/lib/mysql -user 999 -exec chown mysql {} \;
   $ sudo find /var/lib/mysql -group 999 -exec chown :mysql {} \;
   

   Copy

9. Test mysql

   $ docker compose up mysql
   

   Copy

   If mysql fails to start with something like

   [ERROR] [MY-012526] [InnoDB] Upgrade is not supported after a crash or shutdown with innodb_fast_shutdown = 2. This redo log was created with MySQL 5.7.32-35, and it appears logically non empty. Please follow the instructions at http://dev.mysql.com/doc/refman/8.0/en/upgrading.html
   

   Copy

   then run the following:

   $ docker compose run --rm mysql sh
   $ rm /var/lib/mysql/ib_logfile0
   $ rm /var/lib/mysql/ib_logfile1
   $ mkdir '/var/lib/mysql/#innodb_redo'
   

   Copy

   otherwise, terminate the mysql container.

10. Start Docker as normal and ensure the CMS and frontend load.

⁠Deprecated Tags

The final tags without build numbers of each of these images have corresponding tags that do include the build number. If, for some unforeseen reason, you are unable to upgrade to the recommended releases, or if you need to roll back to the latest before this change was made, you can use these tags instead. Note that the legacy tags may be deleted in the future.

This deprecation is an intentional change to disable "automatic upgrades," so you will need to explicitly update these going forward.

Also note that less precise legacy tags were also previously supported. For example, brightspot/tomcat:8.5.69-jdk8-40 had aliases that included 8.5.69-jdk8, 8.5-jdk8, 8-jdk8, and simply 8. These "partial" tags are no longer supported, and may also be deleted in the future.