For a production Linux VPS, install JasperReports Server from the stand-alone WAR distribution, not the bundled binary installer. Prepare a supported JDK, a local Apache Tomcat installation, and a supported database (local or remote), then configure the WAR package’s buildomatic properties and run ./js-install.sh while Tomcat is stopped. The binary installer bundles Tomcat and PostgreSQL for evaluation; the WAR package gives you administrator control over production components and is the supported production path.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
Choose the deployment method before provisioning the VPS
Jaspersoft documents two traditional installers and also supports containerized deployment. They are not interchangeable operationally.
As an Amazon Associate I earn from qualifying purchases.
| Method | What it supplies | Best use | Production guidance |
|---|---|---|---|
| Stand-alone WAR distribution | JasperReports Server web archive, build scripts, database configuration templates and schema-loading utilities. You provide Tomcat, Java and the database. | Production VPS installations and controlled upgrades. | Official documentation identifies this as the production installer. Production packages are obtained through Jaspersoft Technical Support or a sales representative. |
| Binary installer | Bundles Tomcat and PostgreSQL and can install sample data and sample databases. | Evaluation or a quick trial on a disposable host. | The official guidance describes it as intended for evaluation, not as the normal production deployment. |
| Docker or Kubernetes | Container images and release-specific deployment instructions; Jaspersoft lists certified images, including Tomcat images with JDK 17 or JDK 21 and JDK base images used for buildomatic. | Teams already operating containers, immutable images and persistent storage. | Pin the image and release, keep secrets outside the image, persist repository and database data, and follow the guide for the selected release. |
This guide uses the stand-alone WAR method on a Linux VPS. It assumes the application server runs on the VPS while the database may be on that host or on a separate, reachable server.
What you need before installing
A supported 64-bit Linux host
Provision a supported 64-bit Linux VPS. Ubuntu, Debian and CentOS-style systems can work when the selected JasperReports Server release supports the distribution and architecture. Check the release’s platform matrix before ordering the server; Java and Tomcat compatibility is release-specific.
Reserve a DNS name for the service and plan firewall rules before exposing it. Keep SSH restricted to administrative addresses where possible, and expose only the HTTP/HTTPS path that your reverse proxy or Tomcat actually uses. Do not leave database ports open to the public internet merely because the database is remote.
Capacity and persistent storage
The installation documentation does not publish a universal minimum CPU, RAM or disk requirement. Size the VPS from the workload instead: concurrent users, report complexity, scheduled jobs, export volume, repository growth, database activity and log retention. Allocate persistent storage for the Tomcat installation, JasperReports repository, application and build logs, temporary export files and database backups. A small evaluation host and a busy reporting service have very different resource profiles.
Java Development Kit
Install a JDK version supported by the exact JasperReports Server release. Set JAVA_HOME to that JDK, not merely to a Java runtime, and verify both the interactive shell and the account that will run Tomcat:
java -version
echo "$JAVA_HOME"
"$JAVA_HOME/bin/java" -versionIf those commands identify different Java installations, correct the service environment before running buildomatic. The JDK used to build and configure the server must be compatible with the JDK used by Tomcat.
Apache Tomcat
Install a supported Apache Tomcat release locally on the VPS. The service account should own the Tomcat installation, deployed application, temporary directories and log paths that JasperReports Server must write. Record the absolute installation path; you will use it as appServerDir.
For JasperReports Server 10.1.0, the documentation states that Tomcat 11.0.x is supported when the system uses JDK 17 or JDK 21. That 10.1.0 combination also requires an additional JAVA_OPTS configuration step. Do not assume that a Tomcat version supported by 10.1.0 is supported by an older or newer JasperReports Server release; verify the matrix for your release.
A supported database
JasperReports Server supports databases such as PostgreSQL, MySQL, Oracle, SQL Server and DB2, subject to the release’s support matrix. Create a database, login and password before running the installer. The installer creates and loads the JasperReports schema, so the database must be running and the credentials must have the permissions required by the release.
A remote database is valid. The application server still belongs on the Linux VPS, while the database server can be elsewhere if routing, firewall rules, database access control and TLS requirements permit the connection. Test connectivity from the VPS rather than from your workstation.
Provision the VPS and lock down access
- Create the VPS with a supported 64-bit Linux image and apply current operating-system security updates.
- Create a dedicated service account for Tomcat/JasperReports Server. Give it ownership of the Tomcat directories and the writable repository, temporary and log locations; avoid running the application as
root. - Assign a DNS name and, if a reverse proxy will terminate TLS, decide whether Tomcat should listen only on an internal interface.
- Allow SSH only from administration networks where practical. Open HTTP or HTTPS only as required by your front-end design. Permit the database port from the VPS’s address, not from every internet address.
- Set a backup policy for the database, repository, configuration and encryption keystore before production data is loaded.
Install Java and establish a consistent environment
Use the distribution’s package manager or your organization’s approved JDK distribution, then configure JAVA_HOME for both your shell and the Tomcat service. A shell profile alone is insufficient when systemd or another service manager starts Tomcat with a restricted environment.
After setting the variable, verify the path and version:
echo "$JAVA_HOME"
java -version
"$JAVA_HOME/bin/java" -versionKeep a note of the selected JDK major version. JasperReports Server 10.1.0’s documented Tomcat 11 path is specifically JDK 17 or JDK 21, with the extra release-required JVM options applied later.
Install and prepare Tomcat
- Install the Tomcat release listed as supported for your JasperReports Server version.
- Set the Tomcat service account as owner of the installation and directories that will receive the application, generated files and logs.
- Configure the service to use the same supported JDK identified by
JAVA_HOME. Confirm the service environment rather than relying only on an interactive shell. - Record the absolute Tomcat path, for example, the directory you will place in
appServerDir. Do not use a path to a different test installation. - Stop Tomcat before running the JasperReports build scripts. Running buildomatic against a live server can leave deployment or database work in an indeterminate state.
Do not deploy the WAR manually first and then run the installer. The WAR distribution’s buildomatic scripts perform database setup and deployment-related work in the sequence expected by the package.
Prepare a local or remote database
Local database
Install the supported database engine on the VPS or on a separate internal host, create the target database and login, and confirm that the database service starts at boot. Use a dedicated database and credentials for JasperReports Server rather than an administrator account used by unrelated applications.
Remote database
- Create the database and login on the database server according to the database vendor’s rules.
- Allow connections from the VPS address in the database firewall and access-control configuration.
- Allow the database port through any network security group between the hosts.
- From the VPS, test name resolution and a database login with the same host, port, database name and user that will be entered in the JasperReports properties.
- Keep the database running while
js-install.shcreates and loads the schema.
A remote database does not remove the need for a local application server. Tomcat, the JasperReports web application and build scripts remain on the Linux VPS.
Recommended Free Tools
Unpack the WAR distribution and configure buildomatic
Obtain the production WAR package through Jaspersoft Technical Support or a sales representative and extract it into a protected working directory on the VPS. The package contains the web archive plus scripts and configuration templates under buildomatic.
Inside buildomatic/sample_conf/, locate the database-specific properties template for your database. Copy the appropriate template into buildomatic, then edit the resulting properties file (commonly master.properties in the WAR distribution) with the values for your installation.
Set, at minimum, the values that identify:
- Database type and connection details: host, port when applicable, database name, username and password.
appServerType=tomcat.appServerDir, pointing to the intended Tomcat installation’s absolute path.- Any release-specific repository, schema or application settings required by the selected template.
Protect the properties file because it contains database credentials. Restrict its permissions to administrators and the service account as appropriate, and remove temporary copies that contain the password.
Install the JDBC driver when the database requires it
The selected database may require a vendor JDBC driver that is not included in the package or not placed where Tomcat can load it. Install the driver version required by the JasperReports Server release and database vendor, following the release instructions. Oracle, SQL Server and DB2 installations commonly require explicit driver handling; a missing or incompatible driver produces connection or class-loading errors during buildomatic or startup.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallRun js-install.sh in the correct order
Start the database, stop Tomcat, and execute buildomatic from the package’s buildomatic directory:
cd /path/to/jasperreports-server/buildomatic
./js-install.shThe normal command installs JasperReports Server and JasperReports Web Studio, and loads the sample data and sample databases supplied by the distribution. If you do not want those samples, use the minimal form:
cd /path/to/jasperreports-server/buildomatic
./js-install.sh minimalThe minimal form omits sample data and sample databases. Choose it for a cleaner production repository when you have no need for demonstration content. Do not run both forms casually against the same partially initialized database; if a run fails, inspect the logs and correct the cause before deciding whether a clean database is required.
Watch the command output for database authentication failures, unreachable hosts, permission errors, missing JDBC classes, incorrect Tomcat paths and Java configuration problems. Buildomatic logs are written below buildomatic/logs/; preserve the relevant log when diagnosing a failed run.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Apply JVM, license and encryption settings
JVM options
Apply the Java options required by the JasperReports Server release and your Tomcat launch method. For the documented JasperReports Server 10.1.0 combination of Tomcat 11.0.x with JDK 17 or JDK 21, an additional JAVA_OPTS step is required. Use the exact option set and placement specified by the 10.1.0 installation documentation; do not copy options from a different release or service manager without checking compatibility.
After editing the service configuration, verify the effective JVM command line or startup log so you know the options are actually passed to Tomcat. A value placed only in an administrator’s shell profile will not necessarily reach a system service.
License setup
Complete the license setup required for your edition and entitlement after installation. Keep license files in a protected location, document who can replace them, and confirm that the running service can read them. A successful database installation does not by itself complete licensing.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteProtect the generated keystore
Installation automatically generates encryption keys in a Jaspersoft keystore. Treat that keystore as a security-critical production asset: restrict filesystem access to the service and authorized administrators, include it in an encrypted backup plan, and test that the backup can be restored. Losing the keystore can prevent the instance from decrypting protected configuration or credentials after a migration.
Configure browser-rendered exports
Install and configure Chrome or Chromium if your users need PDF or other exports that rely on browser rendering. The browser is an operational dependency, not merely a client-side convenience. Confirm that the Tomcat service account can execute the configured browser binary and access any required temporary directory. If browser-based exports fail while ordinary reports work, check the browser installation, executable path, permissions and application logs.
Start Tomcat and verify the installation
- Start Tomcat using the installation’s Linux startup script:
/path/to/tomcat/bin/startup.sh- Check the Tomcat and JasperReports Server application logs while the web application deploys.
- Confirm that the application reaches the configured database and that the repository loads without schema or permission errors.
- Open the service through the intended DNS name and HTTP/HTTPS path, preferably through the same reverse proxy and TLS configuration that production users will use.
- Sign in with the administrator credentials created for the installation, verify that the expected repository and Web Studio components are present, and run a small report or export appropriate to your configuration.
- Check that scheduled jobs, logs, backups and keystore permissions match your operating procedure before handing the URL to users.
Deployment failures usually appear in Tomcat or JasperReports application logs rather than in a browser’s generic error page. Keep the buildomatic log and the corresponding Tomcat startup log together when investigating an issue.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Remote database and local application server: a practical layout
A common production topology has three trust zones: users reach a reverse proxy over HTTPS; the proxy forwards to Tomcat on the Linux VPS; Tomcat connects to PostgreSQL or another supported database over a private network. In that design:
Free tools Windows power users keep installed
One-click scans. No signup required.
- Only the proxy-facing HTTP/HTTPS port and restricted SSH need internet exposure.
- The database accepts connections from the VPS address or private subnet, not the public internet.
- Database credentials remain in the protected buildomatic configuration and the server’s secured runtime configuration.
- Backups cover both database contents and the JasperReports repository and keystore.
The installer still needs live database access while it creates and loads the schema. A database that will be available only after the installation window cannot satisfy that step.
Binary installer versus WAR: operational trade-offs
| Decision axis | Binary installer | Stand-alone WAR |
|---|---|---|
| Support status | Evaluation-oriented according to the official documentation. | Production installation path. |
| Component ownership | Tomcat and PostgreSQL are bundled, reducing initial setup choices. | You administer the supported JDK, Tomcat and database versions. |
| Database location | Designed around its bundled database for a quick trial. | Supports a local or remote supported database configured in properties. |
| Operational control | Convenient for a disposable demonstration host. | Explicit control over patching, firewalling, service accounts, backups and upgrades. |
| Samples | Can include sample data and sample databases. | Normal mode includes samples; minimal omits them. |
For a VPS that will hold real reports, users or schedules, the WAR method avoids coupling production to bundled evaluation components. For a short-lived proof of concept, the binary installer can reduce setup effort, but plan a fresh WAR-based deployment rather than treating the evaluation host as the production baseline.
Container deployment on a VPS
Docker or Kubernetes can be appropriate when your team already manages container images, persistent volumes, secrets and upgrades. Jaspersoft documents container deployment and identifies certified image combinations, including Tomcat with JDK 17 or JDK 21 and JDK base images used for buildomatic.
For a containerized VPS installation:
- Pin the exact image tag and JasperReports Server release instead of tracking a moving tag.
- Persist the repository, database data and any required keystore outside the container’s writable layer.
- Inject passwords and license material through a secret mechanism rather than baking them into an image.
- Apply the release-specific platform and compatibility instructions, including the documented Java and Tomcat combinations.
- Define a rollback plan that restores a compatible database, repository and keystore together.
Containers change the operational model; they do not eliminate the need for supported Java, database connectivity, backups or secure key handling.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Troubleshoot the failures that stop most installations
JAVA_HOME or Java-version errors
- Run
echo "$JAVA_HOME"andjava -versionin the shell used for buildomatic. - Inspect the Tomcat service environment separately; it may point to another JDK.
- Confirm that the JDK major version is supported by your JasperReports Server and Tomcat release.
- For 10.1.0 with JDK 17 or JDK 21 and Tomcat 11.0.x, verify that the required additional
JAVA_OPTSconfiguration is present.
Database connection or authentication failures
- Confirm the database is running during installation.
- Check the host, port, database name, username and password in the copied properties template.
- Test the route and database login from the VPS, not only from another machine.
- Review firewall and database access-control rules for the VPS address.
- Check that the database user has the permissions needed to create and load the JasperReports schema.
Missing JDBC driver errors
Read the buildomatic or Tomcat log for the missing class name, then install the vendor JDBC driver required by the selected database and JasperReports Server release. Oracle, SQL Server and DB2 deployments are especially likely to require an explicit driver installation step. Restart or rerun the relevant process only after the driver is in the location expected by the release documentation.
Wrong Tomcat deployment
Verify that appServerDir names the Tomcat instance you intend to run. Multiple Tomcat installations are a common cause of a successful build followed by an unchanged web application: buildomatic deployed to one directory while the service starts another.
Permission and service-account errors
Check ownership and write access for Tomcat’s application, temporary and log directories, the JasperReports repository and the keystore. Avoid solving a permission error by running Tomcat as root; correct ownership for the dedicated service account instead.
Export failures
If ordinary report pages work but PDF or browser-rendered exports fail, verify that Chrome or Chromium is installed, executable by the Tomcat account and configured as required. Inspect application logs for the browser path, sandbox or temporary-directory error.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Where to look first
buildomatic/logs/for schema creation, deployment and configuration failures.- Tomcat logs for application deployment, class-loading and JVM errors.
- JasperReports Server application logs for repository, export, scheduling and database errors.
- The effective service environment for Java, JVM options, paths and permissions.
Production handover checklist
- WAR distribution selected for the production host.
- Supported 64-bit Linux, JDK, Tomcat and database versions verified against the release matrix.
JAVA_HOMEis consistent for buildomatic and the Tomcat service.- Database connectivity, credentials and required JDBC driver tested from the VPS.
appServerType=tomcatand the correctappServerDirset in the buildomatic properties.- Tomcat stopped while
./js-install.shor./js-install.sh minimalruns. - Required JVM options and, for the 10.1.0 JDK 17/21 path, the additional
JAVA_OPTSconfiguration applied. - License setup completed.
- Generated Jaspersoft keystore access restricted and backups protected.
- Chrome or Chromium installed if browser-based exports are required.
- Firewall, TLS, service-account and database access rules reviewed.
- Database, repository, configuration, logs and keystore included in tested backups.
- Tomcat and JasperReports logs reviewed after startup, with a test report and export completed.
Final recommendation
Use the stand-alone WAR distribution for a JasperReports Server production VPS. It requires more deliberate preparation than the binary installer, but it keeps Java, Tomcat, database location, firewall policy, backups and upgrade timing under your control. The repeatable sequence is: verify the release matrix, provision the secured host, install the supported JDK and Tomcat, prepare a reachable database, configure the WAR package’s buildomatic properties, stop Tomcat, run the appropriate js-install.sh command, apply JVM and license settings, protect the generated keystore, configure browser exports when needed, then start Tomcat and validate the logs and application.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
