Installing JasperWho?

JasperWho? is a standard Laravel application. The setup is intentionally slim — pull the repository, install dependencies, configure the environment, migrate the database. A standard installation is up and running in under 30 minutes.

---

What You Don't Need

Before listing what is required, it is worth being explicit about what is not:

• No Java — the render engine is pure PHP. No JVM, no Java runtime, no Java SQL drivers.
• No Node.js / npm / Vite — the frontend assets are pre-built and bundled with the repository.
• No Jaspersoft Server — JasperWho? is entirely self-contained.
• No Docker — optional for the database only, not required for the application itself.

---

System Requirements

Requirement	Notes
PHP >= 8.2	With common extensions: pdo, pdo_mysql, mbstring, xml, simplexml, gd, zip, curl, bcmath, fileinfo, openssl
Composer	PHP dependency manager — getcomposer.org
MySQL or MariaDB	JasperWho?'s own application database. A Docker container works fine if no local instance is available.
poppler-utils	Provides pdftoppm, used for generating report thumbnails. Install via apt install poppler-utils.
Supervisor	Keeps the Laravel queue worker running for background jobs (thumbnail generation, purge tasks).
Apache2 or nginx	Optional reverse proxy. Not required for local or development setups.
php-sqlsrv / pdo_sqlsrv	Only required when connecting to Microsoft SQL Server as a report data source. Not needed otherwise.

Bundled Dependencies

The following components are bundled with JasperWho? — no separate installation required:

Component	Purpose
JasperPHP	Pure PHP render engine — parses .jrxml and generates PDFs via TCPDF. Installed automatically by Composer.
GoogleLog Viewer

In-browser Laravel log viewer for monitoring application logs. Scribe Generates the interactive API documentation from source annotations. Material Design Icons Icon set used throughout the frontend. Ace Editor In-browser code editor for writing SQL queries. Logo & Color Concept Visual identity by sinister-labs. Jaspersoft Studio 6.21.5 Desktop IDE for designing .jrxml report templates. Installed separately on the designer's machine — not on the server. Download here.

---

Installation

1. Pull the Repository

git clone <repository-url> jasperwho
cd jasperwho

2. Install PHP Dependencies

composer install --no-dev --optimize-autoloader

3. Set Up the Database

Create a MySQL or MariaDB database for JasperWho?. If no local database server is available, a Docker container is the quickest path:

docker run -d \
  --name jasperwho-db \
  -e MYSQL_ROOT_PASSWORD=secret \
  -e MYSQL_DATABASE=jasperwho \
  -p 3306:3306 \
  mysql:8

4. Configure the Environment

cp .env.example .env
php artisan key:generate

Open .env and configure at minimum the database connection and application URL:

APP_URL=http://your-domain-or-ip

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=jasperwho
DB_USERNAME=your_user
DB_PASSWORD=your_password

All other JasperWho?-specific settings (rate limits, history retention, etc.) are documented on the Configuration and Data Models page.

5. Run Migrations

php artisan migrate --force

This creates all required database tables. Afterwards, run the seeder to create the admin account and base configuration:

php artisan db:seed

6. Set File Permissions

chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

7. Install poppler-utils

apt install poppler-utils

Required for thumbnail generation. Verify the installation with pdftoppm -v.

---

Supervisor — Background Jobs

JasperWho? uses Laravel's queue system for background tasks: generating thumbnails after rendering, purging old history records and print tasks, and cleaning up orphaned files. Supervisor keeps the queue worker alive.

Create a Supervisor configuration file, e.g. /etc/supervisor/conf.d/jasperwho-worker.conf:

[program:jasperwho-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/jasperwho/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/jasperwho/storage/logs/worker.log
stopwaitsecs=3600

Then reload Supervisor:

supervisorctl reread
supervisorctl update
supervisorctl start jasperwho-worker:*

---

Web Server (Optional Reverse Proxy)

For production use, running JasperWho? behind a reverse proxy is recommended. Both Apache2 and nginx work well.

nginx

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/jasperwho/public;

    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Apache2

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/jasperwho/public

    <Directory /var/www/jasperwho/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Ensure mod_rewrite is enabled: a2enmod rewrite.

---

Managed Hosting

If you prefer not to manage infrastructure yourself, JasperWho? can be hosted and operated for you. Instances run exclusively in Germany on Hetzner hardware — reliable, fast, and GDPR-compliant by location.

Cloud-hosted JasperWho? works well for most use cases. Depending on your network connection to the hosting location, render requests may see slightly higher latency compared to a locally deployed instance — typically not noticeable, but worth considering for high-frequency, latency-sensitive workloads like real-time label printing on the shop floor.

For managed hosting enquiries, get in touch directly.