Skip to content

Installation

Requirements

  • Linux for the documented Apache/systemd production path.
  • PHP CLI and web runtime with pgsql and curl; mail() is optional.
  • PostgreSQL client/server.
  • Apache modules alias, rewrite, proxy, and proxy_http.
  • Docker Engine with the Compose plugin.
  • rsync, systemctl, and passwordless non-interactive sudo for scheduler management as currently coded.
  • acugis-report-server.war, which is not built or included by this repository.
  • For the current Compose file, docker/report-server/postgresql-42.7.3.jar.
  • Optional jasperstarter to compile uploaded JRXML; otherwise upload a compiled .jasper.

No package lockfile, Composer manifest, Maven/Gradle project, Makefile, or other service build manifest is present.

Database bootstrap

createdb jasper_reports
psql -d jasper_reports -f database/schema.sql

The application database connection is hardcoded in config.php to localhost:5432, database jasper_reports, user postgres, and a committed password. Replace and rotate that secret before use. JRS_DB_HOST, JRS_DB_PORT, JRS_DB_NAME, JRS_DB_USER, and JRS_DB_PASS are advertised by the old README and installer but are not read by current code.

Create a report datasource through reports/datasources.php or SQL:

INSERT INTO public.jasper_datasource
    (name, host, port, dbname, username, password, schema_name)
VALUES
    ('MainPG', 'host.docker.internal', 5432, 'report_db', 'report_user', 'REDACTED', 'public');

Use a host reachable from the Tomcat container. The datasource name becomes the _dataSource value and JNDI resource jdbc/MainPG.

Manual installation

  1. Copy the service to the web root.
  2. Make these paths writable by the PHP/systemd user (www-data):
install -d -o www-data -g www-data -m 0775 \
  reports/json assets/reports docker/report-server/reports \
  schedules schedules/logs schedules/output
  1. Configure config.php and the supported environment variables in Configuration.
  2. Add an Apache alias or virtual host. The supplied installer uses both /jasper-report-service and /jasper-report-services, with /jasper-report-services/ as its advertised URL.
  3. Generate the Tomcat context:
php reports/generate_jasper_context.php

This web-oriented script applies Central login/service ACL checks even when invoked by CLI if Central auth is enabled. 6. Start the report server as described below. 7. Open /jasper-report-services/.

Docker report server

The Compose definition runs stock tomcat:9-jdk11; it does not build Dockerfile. From docker/report-server:

docker compose config
docker compose up -d
docker compose logs report-server

Before starting, provide:

  • acugis-report-server.war
  • postgresql-42.7.3.jar
  • generated context.xml
  • report files under reports/

Compose publishes host port 9099 to container port 8080 and mounts:

Host Container
./reports /home/tomcat/apache-tomcat-9.0.113/jasper_reports/reports
./context.xml /usr/local/tomcat/conf/context.xml
./acugis-report-server.war /usr/local/tomcat/webapps/ROOT.war
./postgresql-42.7.3.jar /usr/local/tomcat/lib/postgresql-42.7.3.jar

docker/report-server/DOCKER.md describes a stale ./config volume and different report paths; do not use that volume procedure with the current Compose file.

Image build alternative

The checked-in Dockerfile uses tomcat:9.0-jdk11-temurin, copies the WAR as ROOT.war, and downloads PostgreSQL JDBC 42.7.4 as postgresql-jdbc.jar:

docker build -t qcarta-jasper-report-server docker/report-server

The repository provides no Compose override or production run command for this image. Mount context.xml and the report directory at paths expected by the WAR before adopting it.

Installer

On Debian/Ubuntu:

chmod +x installer.sh
sudo ./installer.sh

JRS_INSTALL_DIR defaults to /var/www/html/jasper-report-services. The script copies files with rsync, sets ownership to www-data, writes /etc/apache2/conf-available/jasper-report-services.conf, enables Apache modules/config, and reloads Apache.

Installer caveats:

  • Its instruction to set JRS_DB_* is stale and ineffective.
  • It does not create/load the database, install dependencies, obtain the WAR/JDBC JAR, generate context, start Compose, configure scheduler sudo policy, configure TLS, or remove committed secrets.
  • It excludes the WAR during rsync and then copies it separately when present.

Local development run

After configuring PostgreSQL:

php -S 127.0.0.1:8080

Open http://127.0.0.1:8080/reports/index.php. Apache rewrite/alias behavior and Central shared UI assets are not reproduced by PHP's development server. Tomcat must still be running at the configured internal URL.

Building from source

The PHP application is interpreted and has no build step or third-party PHP package installation. The repository cannot build acugis-report-server.war; supply that artifact separately.

The optional report-server image can be built from the checked-in Dockerfile:

docker build -t qcarta-jasper-report-server:local docker/report-server

The active Compose file uses image: tomcat:9-jdk11 and bind mounts the WAR/JDBC JAR, so docker compose build does not build this Dockerfile.

Production deployment

  1. Deploy to Linux with Apache/PHP and PostgreSQL on protected networks.
  2. Replace and rotate every committed credential before first start.
  3. Set a reachable Central database DSN so authentication does not fall back to disabled/local-development mode.
  4. Serve only the PHP frontend publicly; keep Tomcat port 9099 private and use the PHP execution/image proxies for ACL enforcement.
  5. Configure TLS at Apache or an upstream reverse proxy.
  6. Restrict write access to report, context, schedule, output, and log directories to the service account.
  7. If scheduling is enabled, provide the narrowly scoped passwordless sudo/systemd permissions required by the current implementation.
  8. Back up the application database plus report definitions, artifacts, templates, schedule output, and generated configuration.

See Deployment for Apache, systemd, reverse-proxy, scaling, health, and monitoring guidance.

Common installation problems

Symptom Verified cause or check
Application DB connection fails Current code ignores JRS_DB_HOST, JRS_DB_PORT, JRS_DB_NAME, JRS_DB_USER, and JRS_DB_PASS; edit the db array in config.php.
Compose starts with missing-file mounts Supply acugis-report-server.war, postgresql-42.7.3.jar, and context.xml before docker compose up.
No datasources appear Apply database/schema.sql, confirm JRS_DB_SCHEMA, and ensure enabled jasper_datasource rows exist.
Jasper cannot resolve a datasource Regenerate context.xml, restart Tomcat, and make the database host reachable from the container.
Uploaded JRXML does not compile Install jasperstarter on the PHP host or upload a compiled .jasper file.
Authenticated pages return 503 The resolved Central DSN is configured but unreachable or required Central tables are absent.
Scheduler save reports systemd failure Verify writable schedule/unit paths, enabled PHP exec(), systemctl, non-interactive sudo policy, and www-data ownership.
Enhanced recurrence is not retained The checked-in schema lacks the optional recurrence columns; see Database.