- Introduction
- Prerequisites
- Downloading JasperReports Server WAR
- Cloning the repository
- Repository structure
- Build-time environment variables
- Build and run
- Building and running with docker-compose (recommended)
- Building and running with a pre-existing MySQL instance
- Creating a new MySQL instance during build
- Additional configurations
- Runtime variables
- SSL configuration
- Using data volumes 1. Paths to data volumes on Mac and Windows
- Web application
- License
- Logging
- Updating Tomcat
- Customizing JasperReports Server at runtime
- Applying customizations
- Applying customizations manually
- Applying customizations with Docker Compose
- Restarting JasperReports Server
- Logging in
- Troubleshooting
- Unable to download phantomjs
- "No route to host" error on a VPN/network with mask
docker volume inspect
returns incorrect paths on MacOS Xdocker-compose up
fails with permissions error- 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 tested using the MySQL 5.5 database with JasperReports Server 6.3.0.
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) docker-compose version 1.12 or higher
- 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 MySQL 5.5 database. If you do not currently have a MySQL instance, you can create a MySQL container at build time.
Download the JasperReports Server commercial zip archive from the Support
Portal and copy it to the resources
directory of your archive. For example,
if you have downloaded the archive to your ~/Downloads directory:
$ cp ~/Downloads/jasperreports-server-6.3.0-bin.zip resources/
Clone the JasperReports Server Docker github repository at https://github.com/TIBCOSoftware/js-docker:
$ git clone https://github.com/TIBCOSoftware/js-docker
$ cd js-docker
When you clone the github repository, the following files are placed on your machine:
Dockerfile
- container build commandsdocker-compose.yml
- sample configuration for building and running via docker-compose.env
- sample file with environment variables for docker-composeREADME.md
- this documentresources\
- directory where you put your JasperReports Server zip file or other files you want to copy to the containerREADME.md
- short description ofresources
structure
scripts\
entrypoint.sh
- sample runtime configuration for starting and running JasperReports Server from the shell
At build time, JasperReports Server uses the following environment variables.
These variables can be set directly in the Dockerfile
.
In addition, if you are using docker-compose, many of these variables
can be set in the docker-compose.yml
or the .env
file.
See the
Compose file reference
for more information:
DB_USER
- database usernameDB_PASSWORD
- database passwordDB_HOST
- database hostDB_PORT
- database portDB_NAME
- JasperReports Server database nameJRS_DBCONFIG_REGEN
- When true, forces database configuration regeneration on container run. This variable can be used to point an already existing JasperReports Server container to a new MySQL server.JRS_HTTPS_ONLY
- When true, enables HTTPS-only mode. HTTPS-only requires modifications to theDockerfile
; see SSL configuration and the comments in theDockerfile
for details. Note thatJRS_HTTP_ONLY
must be set directly in theDockerfile
, because it requires additional configuration.
Compose requires the following additional variables to set up the generated MySQL container. If these variables are not set, MySQL will be generated with no access restrictions.
MYSQL_USER
MYSQL_PASSWORD
docker-compose.yml
provides a sample
Compose implementation of
JasperReports Server with MySQL 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
To build and run a JasperReports Server container with a pre-existing MySQL 5.5 instance, execute these commands in your repository:
$ docker build -t jasperserver-pro:6.3.0 .
$ docker run --name some-jasperserver -p 8080:8080 \
-e DB_HOST=some-external-mysql -e DB_USER=username \
-e DB_PASSWORD=password -d jasperserver-pro:6.3.0
Where:
jasperserver-pro:6.3.0
is the image name and version tag for your build. This image will be used to create containers.some-jasperserver
is the name of the new JasperReports Server container.some-external-mysql
is the hostname, fully qualified domain name (FQDN), or IP address of your MySQL server.username
andpassword
are the user credentials for your MySQL server.
To build and run JasperReports Server with a new MySQL container you can use linking:
$ docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=password \
-d mysql:5.5
$ docker build -t jasperserver-pro:6.3.0 .
$ docker run --name some-jasperserver --link some-mysql:mysql \
-p 8080:8080 -e DB_HOST=some-mysql -e DB_USER=db_username \
-e DB_PASSWORD=db_password -d jasperserver-pro:6.3.0
Where:
some-mysql
is the name of your new MySQL container.username
andpassword
are the user credentials to use for the new MySQL container and JasperReports Server container.mysql:5.5
MySQL 5.5 is the MySQL image from Docker Hub.jasperserver-pro:6.3.0
is the image name and version tag for your build. This image will be used to create containers.some-jasperserver
is the name of the new JasperReports Server container.db_username
anddb_password
are the user credentials for accessing the MySQL server. Database settings should be modified for your setup.
Runtime variables are set to sensible defaults and in general do not
require changes. However you can change them, for example, to adjust
Java options for running the JasperReports Server container.
See the Dockerfile
for pre-defined environment variables.
To enable generation and configuration of a self-signed certificate for the JasperReports Server container at build time:
- Locate and uncomment the SSL section in the
Dockerfile
. This commented section containsENV
andRUN
commands to set up variables for key dname, keystore password,HTTPS_PORT
and HTTPS-only mode for JasperReports Server. - Run
keytool
to generate a new key and keystore. - Edit your Tomcat configuration to use the new keystore by default.
Docker recommends 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.
Data volumes are also enabled by default in docker-compose.yml
, see
Building and running with docker-compose
for more information.
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](https://docs.docker.com/engine/tutorials/dockervolumes/#/ important-tips-on-using-shared-volumes) for more information.
On Mac and Windows, you must mount a volume as a directory and reference the local path. 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=root -e
DB_PASSWORD=root -d jasperserver-pro:6.3.0
By default, the JasperReports Server Docker container stores the web
application data in /usr/local/tomcat/webapps/jasperserver-pro
. To create a
locally-accessible named volume, run the following commands at container
generation time:
$ docker volume create --name some-jasperserver-data
$ docker run --name some-jasperserver \
-v some-jasperserver-data:/usr/local/tomcat/webapps/jasperserver-pro \
jasperserver-pro:6.3.0
-p 8080:8080 -e DB_HOST=172.17.10.182 -e DB_USER=root -e \
DB_PASSWORD=root -d jasperserver-pro:6.3.0
Where:
some-jasperserver-data
is the name of the new data volume.some-jasperserver
is the name of the new JasperReports Server container.jasperserver-pro:6.3.0
is 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.
Now you can access the JasperReports Server web application
locally. Run docker volume inspect jasperserver-data
to determine the storage
path and additional details about the new volume.
If you want to define the local volume path manually, you cannot use named
volumes. Instead, modify docker run
like this:
$ docker run --name some-jasperserver -v \
/some-path/some-jasperserver-data:/usr/local/tomcat/webapps/jasperserver-pro \
jasperserver-pro:6.3.0
Where:
/some-path/some-jasperserver-data
is a local path that will be mounted.
By default, the JasperReports Server Docker container expects to find the
license in the
/usr/local/share/jasperreports-pro/license
directory on your system.
If a license file
is not present at this location, then the 30-day evaluation license is used.
On Linux systems, you can add a license volume and store your commercial license there, for example:
$ docker volume create --name some-jasperserver-license
$ sudo cp jasperserver.license \
/var/lib/docker/volumes/some-jasperserver-license/_data
$ docker run --name some-jasperserver \
-v some-jasperserver-license:/usr/local/share/jasperreports-pro/license \
-p 8080:8080 -e DB_HOST=172.17.10.182 -e DB_USER=root \
-e DB_PASSWORD=root -d jasperserver-pro:6.3.0
Where:
some-jasperserver-license
is the name of the new data volume./var/lib/docker/volumes/some-jasperserver-license/_data
is an example path. It may differ on your system, usedocker volume inspect
to get local path to volume.some-jasperserver
is the name of the new JasperReports Server containerjasperserver-pro:6.3.0
is 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.
See Dockerfile
and scripts/entrypoint.sh
for details.
On Windows and Macintosh, you can mount a directory
with the license resource.
See the Docker documentation for more information.
See also
Paths to data volumes on Mac and Windows.
For additional information about paths on Mac, see
docker volume inspect
returns incorrect paths on MacOS X.
To update your license without data volumes on an existing container:
$ docker cp jasperserver.license \
some-jasperserver:/usr/local/share/jasperreports-pro/license/
$ docker restart some-jasperserver
Where:
some-jasperserver
is the name of the new JasperReports Server container.
Note that you need to stop the JasperReports Server container prior to license update and restart it after.
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=root \
-e DB_PASSWORD=root -d jasperserver-pro:6.3.0
Where:
some-jasperserver-log
is the name of the new data volume for log storage.some-jasperserver
is the name of the new JasperReports Server containerjasperserver-pro:6.3.0
is 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
The JasperReports Server container is based on the tomcat:8.0-jre8 (Apache Tomcat) image from Docker Hub. To upgrade your JasperReports Server base image, you must rebuild the JasperReports Server image with the newer Tomcat. See Build and run for building instructions.
To update an already existing JasperReports Server container to a newer base image, you have to re-create it. If you are using volumes for JasperReports Server, you can preserve web application data between upgrades. This can be useful if you have customizations or configuration changes applied to the default web application:
$ docker stop some-jasperserver
$ docker run --name some-jasperserver-2 -v \
some-jasperserver-data:/usr/local/tomcat/webapps/jasperserver-pro \
-d jasperserver-pro:6.3.0
-p 8080:8080 -e DB_HOST=172.17.10.182 -e DB_USER=root \
-e DB_PASSWORD=root -d jasperserver-pro:6.3.0
Where:
some-jasperserver
is the name of the existing JasperReports Server container.some-jasperserver-2
is the name of the new JasperReports Server container.some-jasperserver-data
is the name of a data volume.jasperserver-pro:6.3.0
is an image name and version tag that is used as a base for the new container.- Database settings should be modified for your setup.
Customizations can be added to JasperReports Server container at runtime
via the /usr/local/share/jasperreports-pro/customization
directory in the
container. All zip files in this directory are applied to
/usr/local/tomcat/webapps/jasperserver-pro
in sorted order (natural sort).
For example:
$ docker volume create --name some-jasperserver-customization
$ sudo cp custom.zip \
/var/lib/docker/volumes/some-jasperserver-customization/_data
$ docker run --name some-jasperserver -v \
some-jasperserver-customization:\
/usr/local/share/jasperreports-pro/customization \
-p 8080:8080 -e DB_HOST=172.17.10.182 -e DB_USER=root \
-e DB_PASSWORD=root -d jasperserver-pro:6.3.0
Where:
some-jasperserver-customization
is the name of the customization data volume.custom.zip
is an archive containing customizations, for example:WEB-INF/log4j.properties
. The archive will be unpacked as-is to the path/usr/local/tomcat/webapps/jasperserver-pro
/var/lib/docker/volumes/some-jasperserver-customization/_data
is an example path. Usedocker volume inspect
to get the local path to the volume for your system.some-jasperserver
is the name of the JasperReports Server container.jasperserver-pro:6.3.0
is an image name and version tag that is used as a base for the new container.- Database settings should be modified for your setup.
See scripts/entrypoint.sh
for implementation details and
docker-compose.yml
for a sample setup of a customization volume via Compose.
This directory can be also mounted as a Data Volume.
You must mount the directory on Windows and Macintosh.
See also
Paths to data volumes on Mac and Windows.
For additional information about paths on Mac, see
docker volume inspect
returns incorrect paths on MacOS X.
To use customizations with docker-compose
, run docker volume inspect
to determine the path of the volume you want and add the license. To reference an
existing volume, modify the YAML file appropriately.
You can also apply customizations manually, either via the docker cp
command
or by modifying files in the web application data volume.
For example:
$ docker cp log4j.properties some-jasperserver:\
/usr/local/tomcat/webapps/jasperserver-pro/WEB-INF/
$ docker restart some-jasperserver
Where:
some-jasperserver
is the name of the JasperReports Server container.
Note that independent of method, you need to restart the
JasperReports Server container (docker restart some-jasperserver
)
if customizations are applied to a running container.
Logging in
To log into JasperReports Server on any operating system:
- Start JasperReports Server.
- Open a supported browser: Firefox, Internet Explorer, Chrome, or Safari.
- Log into JasperReports Server by entering the startup URL in your browser's address field. The URL depends upon your installation. The default configuration uses:
http://localhost:8080/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
For example:
ERROR: for jasperserver Cannot start service jasperserver:
oci runtime error: exec: "/entrypoint.sh": permission denied
This error can occur even if permissions are properly set for entrypoint.sh. To fix this issue:
First, locate the COPY
line
for entrypoint.sh in the Dockerfile:
COPY scripts/entrypoint.sh /
Then, add the following command immediately after the COPY line:
RUN chmod +x /entrypoint.sh
For additional questions regarding docker and docker-compose usage see:
- docker-engine documentation
- docker-compose documentation
Copyright © 2016. TIBCO Software Inc. This file is subject to the license terms contained in the license file that is distributed with this file.
Software Version: 6.3.0-v1.0.4 Document version number: 1016-JSP63-01
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.