Overview¶

QCarta Jasper Service is a PHP front end for publishing, cataloging, authorizing, running, and scheduling Jasper reports. PostgreSQL stores service metadata and datasource credentials; a separate Tomcat 9 container hosts the report WAR and renders reports.

Security notice: config.php and generated/sample Tomcat context files contain committed database credentials. This documentation intentionally omits those values. Replace the credentials, rotate every exposed secret, remove secrets from version control, and restrict generated context files.

Purpose¶

Provide a standalone developer and operator interface around the AcuGIS Jasper report engine: manage report definitions and PostgreSQL datasources, enforce Central ACLs, proxy report output, and automate scheduled delivery.

Major features¶

Publish JRXML, optional compiled Jasper files, and thumbnails.
Maintain PostgreSQL report datasources and generate Tomcat JNDI resources.
Render reports through an ACL-enforcing PHP proxy.
Integrate with the Central session and resource-permission database.
Discover reports through JSON endpoints and the sibling acugis reports CLI.
Run reports manually or with generated systemd services and timers.
Persist output and execution history and optionally email attachments.

Architecture summary¶

The PHP application serves management pages and JSON/runtime endpoints. It stores service metadata in PostgreSQL and report metadata/artifacts on disk. Runtime requests are authorized against an optional Central PostgreSQL database, then proxied to the separate Tomcat/WAR engine. Systemd timers invoke the PHP CLI scheduler, which writes output, records execution status, and optionally delivers email.

flowchart LR
  Client[Browser / API / acugis CLI] --> PHP[PHP Jasper Publisher]
  PHP --> AppDB[(Application PostgreSQL)]
  PHP --> Central[(Central auth and ACL DB)]
  PHP --> Files[(Report definitions and artifacts)]
  PHP --> Tomcat[Tomcat Jasper WAR]
  Timer[systemd timer] --> Runner[PHP schedule runner]
  Runner --> AppDB
  Runner --> Tomcat
  Runner --> Output[(Output and logs)]
  Runner --> Mail[SMTP or PHP mail]

Technology stack¶

Layer	Verified technology
Application	PHP 8-style source using `pgsql`, `curl`, filesystem APIs, and optional `mail()`
Metadata and report datasources	PostgreSQL
Rendering	Externally supplied `acugis-report-server.war` on Tomcat 9 / Java 11
Container deployment	Docker and Docker Compose
Web deployment	Apache with alias, rewrite, and reverse-proxy modules
Scheduling	PHP CLI plus generated systemd oneshot services and timers
UI	Server-rendered PHP, Materialize 1.0.0, Bootstrap 5.3.3, Google Fonts/Icons
CLI integration	Sibling Python 3.10+ Typer-based `acugis` CLI

Documentation¶

Repository structure¶

Path	Purpose
`config.php`, `lib/`	Runtime configuration, database, authentication, ACL, scheduler, mail, and storage logic
`reports/`	Catalog, publisher, viewer, report proxy, datasource administration, and report JSON
`api/`	Discovery, datasource, report, and resource-sync endpoints
`database/schema.sql`	Five-table application schema
`docker/report-server/`	Tomcat/WAR container definitions, JDBC context, report artifacts, and servlet source snapshot
`scripts/`	Schedule runner and Central resource synchronization CLI commands
`schedules/`	Generated EnvironmentFiles, logs, and rendered output
`systemd/`	Generated service and timer units present in this checkout
`deploy/`	Apache reverse-proxy example
`email_tmpl/`	File-based email templates
`debug/`, `debug.php`	Diagnostic endpoints; unsafe for production unless disabled or removed

Key concepts¶

Concept	Meaning
Report key	Lowercase `a-z0-9_-` identifier used as `_repName` and the on-disk filename stem
Report definition	`reports/json/<key>.report.json`, containing display metadata, datasource, format, and parameters
Report datasource	Application DB row converted to a Tomcat JNDI resource named `jdbc/<name>`
Service ACL	Central resource `service:jasper_reports`, controlling management-page access
Report ACL	Central resource `jasper_report:<key>`, controlling view/edit/admin operations
Public report	Report with Central `Public` group `view`; runtime endpoints can authorize it without login
Scheduled run	Database schedule executed by PHP manually or from a generated systemd timer

Typical workflows¶

Configure the application database, apply database/schema.sql, and add a report datasource.
Generate context.xml, provide the WAR/JDBC driver, and start Tomcat.
Publish JRXML through the management UI; optionally provide .jasper and thumbnail files.
Sync reports to Central, assign ACLs, and discover or execute them through the API/CLI.
Create a schedule; the service writes an EnvironmentFile and systemd units, then records each run and optional email delivery.

Fast path¶

Install PHP with pgsql and curl, PostgreSQL, Apache, Docker Compose, and the proprietary/externally supplied acugis-report-server.war.
Replace the committed application database secret in config.php.
Create jasper_reports and apply database/schema.sql.
Add a row to jasper_datasource.
Generate docker/report-server/context.xml.
Supply the WAR and the Compose-required PostgreSQL JDBC JAR, then run docker compose up -d from docker/report-server.
Serve the PHP tree through Apache and open /jasper-report-services/.

See Installation before executing these steps: the current installer contains stale JRS_DB_* guidance, and Compose does not build the checked-in Dockerfile.

Known limitations¶

No dependency/build manifest, automated tests, migration framework, release manifest, release tags, application health endpoint, monitoring integration, Nginx configuration, or automated TLS setup is present.
database/schema.sql lacks the newer scheduler repeat fields that the PHP code uses only when those columns already exist.
Compose and docker/report-server/DOCKER.md disagree; the Compose file is the current executable definition.
Authentication is effectively disabled when no Central DSN can be resolved; code then treats the request as local development/admin.