- Introduction
- Prerequisites
- Installation
- docker build time environment variables
- docker run time environment variables
- Configuring JasperReports Server with volumes
- Build and run
- Initializing the JasperReport Server Repository
- Import and Export for the JasperReports Server repository
- JasperReports Server logs
- Logging in to JasperReports Server
- Troubleshooting
- Docker documentation
This distribution includes a sample Dockerfile and
supporting files for
building, configuring, and running
TIBCO JasperReports® Server
in a Docker container. This sample can be used as is
or modified to meet the needs of your environment.
The distribution can be downloaded from
https://github.com/TIBCOSoftware/js-docker.
This configuration has been certified using the PostgreSQL 9 database with JasperReports Server 6.4+ and with PostgreSQL 10 for JasperReports Server 7.2+
Basic knowledge of Docker and the underlying infrastructure is required. For more information about Docker see the official documentation for Docker.
For more information about JasperReports Server, see the Jaspersoft community.
The following software is required or recommended:
- docker-engine version 1.12 or higher
- (recommended):
- (recommended) docker-compose version 1.12 or higher
- (optional) git
- (optional) TIBCO Jaspersoft® commercial license.
- Contact your sales representative for information about licensing. If you do not specify a TIBCO Jaspersoft license, the evaluation license is used.
- (optional) Preconfigured PostgreSQL, MySQL, Oracle, SQL Server or DB2 database. If you do not currently have a database instance, you can create a database container at deployment time.
Download the js-docker repository as a zip and unzip it, or clone the repository from Github.
To download a zip of js-docker:
- Go to https://github.com/TIBCOSoftware/js-docker
- Select Download ZIP on the right hand side of the screen.
Select Open in Desktop if you have a Git Desktop installed. This will clone the repository for you.
If you have the Git command line installed, you can clone the JasperReports Server Docker github repository at https://github.com/TIBCOSoftware/js-docker
$ git clone https://github.com/TIBCOSoftware/js-docker
$ cd js-dockerThe js-docker github repository contains:
-
Dockerfile- for base Tomcat based image -
Dockerfile-exploded- as above. Gets resources for image build from exploded WAR file installer -
Dockerfile-s3-config- builds an image based on a JasperReports Server image to load config files from S3 before launching app -
docker-compose.yml- sample configuration for building and running via docker-compose -
.env- sample file with environment variables for docker-compose -
README.md- this document -
resources\- directory where you put your JasperReports Server zip file copied into the image at build time -
scripts\- entrypoints for imageentrypoint.sh- Base runtime configuration for a JasperReports Server container. Referred to byDockerfileandDockerfile-exploded.entrypoint-aws.sh- Loads config and license from S3 before starting JasperReports Server. Referred to byDockerfile-s3-config
-
kubernetes\- directory of JasperReports Server Kubernetes configurationREADME.md- JasperReports Server Kubernetes documentation
-
options\- directory of optional configurations and customizations for JasperReports Server containersREADME.md- options documentation- includes creating a JasperReports Server cluster
Download the JasperReports Server WAR File installer zip archive from the TIBCO eDelivery site or build it from a bundled installer Jaspersoft WAR File Installer builder
Copy the installer zip file to the resources directory in the repository structure.
For example, if you have downloaded the zip to your ~/Downloads directory:
$ cp ~/Downloads/TIB_js-jrs_X.X.X_bin.zip resources/- Deploy JasperReports Server images into ECR from an AWS Marketplace AMI
- Define a Postgres RDS instance for the JasperReports Server to use as a repository
- Define ECS tasks to deploy JasperReports Server
- (coming) Deploy JasperReports Server to EKS
These can be passed on the command line with --build-arg, in an env-file, docker-compose.yml, Kubernetes etc.
| Environment Variable Name | Notes |
|---|---|
TOMCAT_BASE_IMAGE |
The Docker image version of Tomcat that is certified for the version of JasperReports Server being deployed. Default: "tomcat:9.0.17-jre8" which is for JasperReports Server 7.2.0. |
HTTP_PORT |
HTTP port Tomcat runs on. Default: "8080" |
HTTPS_PORT |
HTTPS port Tomcat runs on. Default: "8443" |
JRS_HTTPS_ONLY |
Enables HTTPS-only mode. Default: false. |
| A self signed SSL certificate is defined for Tomcat. | |
DN_HOSTNAME |
Self signed certificate host name. Default: "localhost.localdomain" |
KS_PASSWORD |
Keystore password. Default: "changeit" |
POSTGRES_JDBC_DRIVER_VERSION |
Default: 42.2.5. If you change this in the Dockerfile, the new version will be downloaded from https://jdbc.postgresql.org/download.html |
JasperReportsServerVersion |
Used in Dockerfile-s3-config to refer to the version this wrapper image is based on |
These can be passed on the command line with -e, in an env-file, docker-compose.yml, Kubernetes etc.
If the DB_NAME repository database does not exist in the configured Postgresql database, entrypoint.sh will create it.
| Environment Variable Name | Notes |
|---|---|
DB_TYPE |
valid dbTypes are: postgresql, mysql, sqlserver, oracle, db2. Default: postgresql. |
DB_HOST |
database host IP or domain name. Default: postgres |
DB_PORT |
database port. Default: default port for the dbType |
DB_USER |
database username. Default: postgres |
DB_PASSWORD |
database password. Default: postgres |
DB_NAME |
JasperReports Server repository schema name in the database. Default: "jasperserver" |
HTTP_PORT |
HTTP port Tomcat runs on. Default: HTTP_PORT in image |
HTTPS_PORT |
HTTPS port Tomcat runs on. Default: HTTPS_PORT in image |
JAVA_OPTS |
Command line options passed to OpenJDK 8 / Tomcat 9. Optional. The Java heap size of JasperReports Server is automatically managed to conform to the container size. |
JAVA_MIN_RAM_PERCENTAGE |
Java heap minimum percentage in the container. Default: 33.3% |
JAVA_MAX_RAM_PERCENTAGE |
Java heap maximum percentage in the container. Default: 80.0% |
JDBC_DRIVER_VERSION |
optional. for non-PostgreSQL databases. Requires a JDBC driver with the required version accessible through a volume. See Use of Volumes |
POSTGRES_JDBC_DRIVER_VERSION |
optional, Default: 42.2.5. If you change this, the new version will need to be installed by volume as above. See Use of Volumes |
JRS_DBCONFIG_REGEN |
Forces updates to the repository JNDI database configuration plus the JDBC driver in tomcat/lib. Default: false. |
JRS_HTTPS_ONLY |
Enables HTTPS-only mode. Default: false. |
JRS_LOAD_SAMPLES |
Load JasperReports Server samples when creating the database. Default: false |
KS_PASSWORD |
Keystore password. Default: "changeit". Only used if a keystore is being overridden through a new keystore. See new keystore addition through volumes below. |
MOUNTS_HOME |
Directory in the container where mounted volumes will be. In AWS containers loading configs and/or import/exports from S3, this will be the destination directory in the container where S3 contents will be stored. |
S3_BUCKET_NAME |
S3 bucket to be used with a jasperserver-pro:aws image. Referred to in entrypoint-aws.sh |
Docker, Kubernetes and Docker compose best practices recommend the use of data volumes for managing persistent data and configurations. The type and setup of data volumes depend on your infrastructure. We provide sensible defaults for a basic docker installation.
Note that the data in data volumes is not removed with the container and needs to be removed separately. Changing or sharing data in the default data volume while the container is running is not recommended. To share a volume, use volume plugins. See the Docker documentation for more information.
| Description | Path to override in container | Notes |
|---|---|---|
| License | /usr/local/share/jasperreports-pro/license |
Path to contain jasperserver.license file to use. If not provided, a temporary license is used. |
| JasperReports Server customizations | /usr/local/share/jasperreports-pro/customization |
Volume to contain zip files that are unzipped into ${CATALINA_HOME}/webapps/jasperserver-pro. Files are processed in alphabetical order, so duplicate file names can be overridden. |
| Tomcat level customizations | /usr/local/share/jasperserver-pro/tomcat-customization |
Volume to contain zip files that are unzipped into ${CATALINA_HOME}. Files are processed in alphabetical order, so duplicate file names can be overridden. |
| New keystore file | /usr/local/share/jasperserver-pro/keystore |
.keystore files in this volume loaded into /root. The keystore password must be set as the KS_PASSWORD environment variable. |
| Additional default_master installation properties | /usr/local/share/jasperserver-pro/default-master |
default_master_additional.properties file contents appended to default_master.properties. See "To install the WAR file using js-install scripts" in JasperReports Server Installation Guide |
| Include a new version of a JDBC driver for the repository database | /usr/src/jasperreports-server/buildomatic/conf_source/db//jdbc | valid dbTypes are: postgresql, mysql, sqlserver, oracle, db2. Need to set the JDBC_DRIVER_VERSION environment variable to the version number of the driver. |
| Complete JasperReports Server web application | ${CATALINA_HOME}/webapps/jasperserver-pro |
The complete JasperReport Server WAR structure in the external volume. Not expected to be used often - override smaller pieces of the container through the above mounts |
docker run -v external_volume:<path to override in container>
docker-compose:
volumes:
- jrs_license:/usr/local/share/jasperreports-pro/license
If you update the files in a volume listed above, you will need to restart the container, as these are only processed at container start time.
You can mount a volume to a directory on your local machine. For example, to access a license on a local directory on Mac:
docker run --name new-jrs
-v /<path>/resources/license:/usr/local/share/jasperreports-pro/license
-p 8080:8080 -e DB_HOST=172.17.10.182 -e DB_USER=postgres -e
DB_PASSWORD=postgres -d jasperserver-pro:X.X.XVolumes in Docker for Windows need to be under the logged in user's User area ie.
volumes:
- /C/Users/<user>/Documents/License:/usr/local/share/jasperserver-pro/license Windows paths need some help with a Docker Compose environment setting:
COMPOSE_CONVERT_WINDOWS_PATHS=1You can use the Dockerfile-s3-config Dockerfile to have the configuration volumes in S3. The entrypoint-aws.sh loads the files from the given S3_BUCKET_NAME environment variable. See https://community.jaspersoft.com/wiki/building-and-running-jasperreports-server-containers-aws-ecs-and-eks
docker-compose.yml provides a sample
Compose implementation of
JasperReports Server with PostgreSQL server, configured with volumes for
JasperReports Server web application and license, with pre-setup network and
mapped ports. There is also a pre-configured .env file for use with
docker-compose.
To build and run using docker-compose.yml, execute the following commands in
the root directory of your repository:
$ docker-compose build
$ docker-compose up -dNote that you should set the amount of memory and CPU that each JasperReports Server container uses. The options below in the docker-compose.yml are recommended as starting points, and may need to be increased if the container is under heavy load. The entrypoint.sh configures the underlying Java memory settings according to the container memory settings.
mem_limit: 3g
mem_reservation: 1g
cpu_shares: 256To build and run a JasperReports Server container with a pre-existing PostgreSQL instance, execute these commands in your repository:
$ docker build -t jasperserver-pro:X.X.X .
$ docker run --name some-jasperserver -p 8080:8080 \
-e DB_HOST=some-external-host -e DB_USER=username \
-e DB_PASSWORD=password -d jasperserver-pro:X.X.XWhere:
jasperserver-pro:X.X.Xis the image name and version tag for your build. This image will be used to create containers.some-jasperserveris the name of the new JasperReports Server container.some-external-hostis the hostname, fully qualified domain name (FQDN), or IP address of your database server.usernameandpasswordare the user credentials for your repository database server.
To build and run JasperReports Server with a new database container you can use linking:
$ docker run --name some-postgres -e POSTGRES_USER=username \
-e POSTGRES_PASSWORD=password -d postgres:10
$ docker build -t jasperserver-pro:X.X.X .
$ docker run --name some-jasperserver --link some-postgres:postgres \
-p 8080:8080 -e DB_HOST=some-postgres -e DB_USER=db_username \
-e DB_PASSWORD=db_password -d jasperserver-pro:X.X.XWhere:
some-postgresis the name of your new database container.usernameandpasswordare the user credentials to use for the new PostgreSQL container and JasperReports Server container.postgres:10PostgreSQL 10 is the PostgreSQL image from Docker Hub. This can be replaced with other database types that match the dbType environment variable.jasperserver-pro:X.X.Xis the image name and version tag for your build. This image will be used to create containers.some-jasperserveris the name of the new JasperReports Server container.db_usernameanddb_passwordare the user credentials for accessing the database server. Database settings should be modified for your setup.
You can do the same with MySQL, Oracle, SQL Server and DB2.
The docker-compose.yml shows how to launch Jasperreports Server automatically
with a PostgreSQL repository running in Docker. By default, this docker-compose.yml
uses the .env file for configuration purposes. There is also a .env-mysql to
show how an external MySQL database running on the default 3306 port
can be used as a repository.
Set the dbType and DB_* environment variables as outlined above. The default command
of the container - run - will detect whether the repository host exists and
can be connected to, and whether the repository database exists in the host, and
create them as needed. The JRS_LOAD_SAMPLES environment variable can be set to true to load the
JasperReports Server samples and their underlying databases into the repoitory database.
Also there is the standalone init command for the image that allows you to pre-create
the repository database and samples.
docker run --rm \
--env-file .env -e DB_HOST=jasperserver_pro_repository \
--name jasperserver-pro-init \
jasperserver-pro:X.X.X init
The JasperReports Server samples can be loaded via the init command without
setting the JRS_LOAD_SAMPLES environment variable. Add samples as a parameters
to the init command as follows:
docker run --rm \
--env-file .env -e DB_HOST=jasperserver_pro_repository \
--name jasperserver-pro-init \
jasperserver-pro:X.X.X init samples
One maintenance aspect of the JasperReports Server is exporting and importing
content - reports, domains and other metadata - with the repository. The Docker entrypoint.sh
has commands to allow you to run the JasperReports Server image to do imports and exports
directly to a JasperReports Server repository database, leveraging the JRS command line
js-export and js-import tools, documented in the JasperReports Server Administration Guide.
See Jaspersoft Documentation
and search for "Administration" in the page to get the latest.
- Create an 'export.properties' file in a directory, with each line containing parameters for individual imports: zip files and/or directories. See the JasperReports Server Administration Guide - section: "Exporting from the Command Line" for the options.
# Comment lines are ignored, as are empty lines
# Server settings
--output-zip BS-server-settings-export.zip --include-server-settings
# Repository export
--output-zip Bikeshare-JRS-export.zip --uris /public/Bikeshare_demo
# Repository export
--output-dir some-sub-directory
# Organization export. Org has to be created before running this import
--output-zip Bikeshare_org_user_export.zip --organization Bikeshare
- Run the JasperReports Server image with the export command,
defining and passing into the command in one or more volumes
where the
export.propertiesis and the exports are to be stored.
And do either:
- Use existing database running in Docker. Note the network and DB_HOST settings.
docker run --rm \
-v /path/to/a/volume:/usr/local/share/jasperserver-pro/export \
--network js-docker_default -e DB_HOST=jasperserver_pro_repository \
--name jasperserver-pro-export \
jasperserver-pro:X.X.X export /usr/local/share/jasperserver-pro/export
- Use an external repository database. Note the DB_HOST setting.
docker run --rm \
-v /path/to/a/volume:/usr/local/share/jasperserver-pro/import \
-e DB_HOST=domain.or.IP.where.repository.database.is \
--name jasperserver-export \
jasperserver-pro:X.X.X export /usr/local/share/jasperserver-pro/import
After an export run, the export.properties file is renamed in the volume as export-done.properties.
- Create an 'import.properties' file in a directory, with each line containing parameters for individual imports from export zip files and/or directories. See the JasperReports Server Administration Guide - section: "Importing from the Command Line" for the options.
# Comment lines are ignored, as are empty lines
# Server settings
--input-zip BS-server-settings-export.zip
# Repository import
--input-zip Bikeshare-JRS-export.zip
# Import from a directory
--input-dir some-sub-directory
# Organization import. Org has to be created before running this import
--input-zip Bikeshare_org_user_export.zip --organization Bikeshare
-
Place the ZIP files and/or directories into the same directory as the
import.properties. -
Run the JasperReports Server image, defining and passing into the command one or more volumes where the import.properties and the exports are stored.
And do either:
- Use a database instance running in Docker. Note the network and DB_HOST settings.
docker run --rm \
-v /path/to/a/volume:/usr/local/share/jasperserver-pro/import \
--network js-docker_default -e DB_HOST=jasperserver_pro_repository \
--name jasperserver-pro-import \
jasperserver-pro:X.X.X import /usr/local/share/jasperserver-pro/import
- Use an external repository database. Note the DB_HOST setting.
docker run --rm \
-v /path/to/a/volume:/usr/local/share/jasperserver-pro/import \
-e DB_HOST=domain.or.IP.where.database.is \
--name jasperserver-import \
jasperserver-pro:X.X.X import /usr/local/share/jasperserver-pro/import
After an import run, the import.properties file is renamed in the volume as import-done.properties.
Note that, as of JasperReports 7.2.0 at least, there is no way to import a organization export.zip at the highest level (root) without first creating the organization via the JasperReports Server user interface or REST.
Import/Export commands on AWS containers can work with S3 buckets in addition to mounted volumes.
import s3 InputBucketName1/folder InputBucketName2/folder InputBucketName3/folder
export s3 ExportBucketName1/folder ExportBucketName2/folder ExportBucketName3/folder
import mnt Mounted/Directory1 Mounted/Directory2 Mounted/Directory3
export mnt Mounted/Directory4 Mounted/Directory5 Mounted/Directory6
The S3_BUCKET_NAME environment variable is used during import/export to load configuration needed for repository database connections.
The S3 versions of the commands will need read/write permissions to the buckets, so your IAMInstanceRole needs to be set accordingly.
By default, the JasperReports Server log is streamed to the console, so default Docker logging can pick that up.
Beyond the console. there are multiple options for log access, aggregation, and management in the Docker ecosystem. The most common options are:
- volumizing log files
- using docker logging drivers
For the TIBCO JasperReports Server Docker, the default json-file
docker drivers should be sufficient.
In a more complex environment a log collector should be considered. One
example is collecting logs on a remote syslog server.
See the
logging drivers
documentation for
more information.
To volumize the JasperReports Server container log, you can create a container for log storage:
$ docker volume create --name some-jasperserver-log
$ docker run --name some-jasperserver -v \
some-jasperserver-log:/usr/local/tomcat/webapps/jasperserver-pro/WEB-INF/logs \
-p 8080:8080 -e DB_HOST=172.17.10.182 -e DB_USER=postgres \
-e DB_PASSWORD=postgres -d jasperserver-pro:X.X.XWhere:
some-jasperserver-logis the name of the new data volume for log storage.some-jasperserveris the name of the new JasperReports Server containerjasperserver-pro:X.X.Xis the image name and version tag. for your build. This image will be used to create containers.- Database settings should be modified for your setup.
Note that docker containers do not have separate logs. All information is
logged via the driver or application. In the case of the JasperReports
Server container, the main log is output by Tomcat to the docker-engine
via the logging driver, and the application log specific to
JasperReports Server is output to
some-jasperserver-log:/usr/local/tomcat/webapps/jasperserver-pro/WEB-INF/logs
After the JasperReports Server container is up, log into it via URL. The URL depends upon your installation. The default configuration uses:
http://<domain or IP>:8080/jasperserver-pro
or if running on port 80
http://<domain or IP>/jasperserver-pro
Where:
- localhost is the name or IP address of the computer hosting JasperReports Server.
- 8080 is the port number for the Apache Tomcat application server. If you used a different port when installing your application server, specify its port number instead of 8080.
JasperReports Server ships with the following default credentials:
- superuser/superuser - System-wide administrator
- jasperadmin/jasperadmin - Administrator for the default organization
At build-time Docker fails with an error "403: Forbidden" when downloading phantomjs:
2016-09-19 20:54:50 ERROR 403: Forbidden.
This occurs when the phantomjs binary is temporarily unavailable for download.
You can do one of the following: disable the phantomjs download, change the
URL, or use a locally-downloaded phantomjs archive. See Dockerfile for
details. Note that if you had a successful build and the Docker cache has not
been invalidated,
you do not need to re-download phantomjs on a subsequent build.
The default Docker network may conflict with your VPN space.
Change to a different CIDR for the Docker network using --bip.
See the Docker networking documentation
for more information; for Mac, also see
Docker issue 25064.
Due to the nature of Docker for Mac
docker volume inspect returns paths that are relative to the main docker
process. You must either access the path in the container, for example,
/var/lib/docker/volumes/some-jasperserver-license/_data,
or define a volume path instead of a named volume.
This also applies to Docker Compose.
See Using data volumes for defining a local path.
For more information see Docker Community Forums: Host path of volume
The entrypoint.sh tries to connect to the repository database before starting the Server. If there are problems, there will be 5 retries to connect before stopping the process. You can see the problem in the JasperReports Server container log.
PS C:\Users\user\Documents\GitHub\js-docker> docker run --rm --env-file .env-mysql
--name jrs-init-test -v /C/Users/user/Documents/Docker/buildomatic/mysql/jdbc:/usr/src/jasperreports-server/buildomatic/conf_source/db/mysql/jdbc
jasperserver-pro:X.X.X init
[exec] Execute failed: java.io.IOException: Cannot run program "git": error=2, No such file or directory
BUILD FAILED
/usr/src/jasperreports-server/buildomatic/bin/validation.xml:493: The following error occurred while executing this line:
/usr/src/jasperreports-server/buildomatic/bin/validation.xml:374: The following error occurred while executing this line:
/usr/src/jasperreports-server/buildomatic/conf_source/db/mysql/db.xml:73: The following error occurred while executing this line:
/usr/src/jasperreports-server/buildomatic/bin/validation.xml:411: The following error occurred while executing this line:
/usr/src/jasperreports-server/buildomatic/bin/validation.xml:468: Invalid username/password combination: [jaspersoftX/jaspersoft].
Treating problem with JDBC connection as unrecoverable
Total time: 0 seconds
saw 0 OK connections, not at least 1
test_connection returned fail
You will need to review the network connection between the Server and the database instance, and review DB_* environment settings.
For additional questions regarding docker and docker-compose usage see:
- docker-engine documentation
- docker-compose documentation
Copyright © 2019. TIBCO Software Inc. This file is subject to the license terms contained in the license file that is distributed with this file.
TIBCO, Jaspersoft, and JasperReports are trademarks or registered trademarks of TIBCO Software Inc. in the United States and/or other countries.
Docker is a trademark or registered trademark of Docker, Inc. in the United States and/or other countries.